major-domo-umbrella/CLAUDE.md

Major Domo — Ecosystem

SBA fantasy baseball league management system: Discord bot, FastAPI database API, Vue.js website. This is the parent directory containing all Major Domo sub-projects. Do not develop here — work in the appropriate sub-project directory.

Sub-Projects

Directory	Gitea Repo	What It Does	Tech
discord-app-v2/	cal/major-domo-v2	Discord bot — slash commands, transactions, trades, dice, voice channels	Python 3.13, discord.py, Pydantic v2
database/	cal/major-domo-database	Central API — all league data, player/team/transaction CRUD, game results	FastAPI, Peewee ORM, PostgreSQL
sba-website/	cal/sba-website	Public league website — standings, stats, schedules, leaderboards	Vue 3, TypeScript, Vite, Bootstrap 5

Supporting Directories

Directory	Purpose
dev-storage/	Mapped volume for local Docker containers to share storage
dev-logs/	Discord bot log mounts
.archive/	Archived files: legacy scripts, old databases, dead code

Architecture — How Everything Connects

┌─────────────────────┐
│   Discord Users     │
│   (SBA server)      │
└────────┬────────────┘
         │ slash commands
         ▼
┌─────────────────────┐     HTTP/API      ┌──────────────────────┐
│   Discord Bot       │ ──────────────►   │   Database API       │
│   discord-app-v2/   │                   │   database/          │
│   (akamai)          │                   │   sba.manticorum.com │
└─────────────────────┘                   └──────────┬───────────┘
                                                     │  Peewee ORM
┌─────────────────────┐     HTTP/API                 ▼
│   Website           │ ──────────────►   ┌──────────────────────┐
│   sba-website/      │                   │   PostgreSQL          │
│   (akamai:803)      │                   │   sba_postgres        │
└─────────────────────┘                   └──────────────────────┘
                                                     │
                                          ┌──────────────────────┐
                                          │   Redis (optional)   │
                                          │   sba_redis           │
                                          └──────────────────────┘

Deployment Topology

Service	Host	Container	Port
Discord Bot	ssh akamai	major-domo-discord-app-1	— (outbound only)
Database API	ssh akamai	sba_db_api	801
PostgreSQL	ssh akamai	sba_postgres	5432
Redis	ssh akamai	sba_redis	6379
Website	ssh akamai	sba-website-sba-web-1	803
Database API (dev)	ssh sba-db	dev container	801

Environments

	Prod	Dev
API Host	ssh akamai	ssh sba-db
Bot Host	ssh akamai	local

Cross-Project Conventions

• CI/CD: All repos use Gitea Actions. Docker images built on CalVer tag push (YYYY.M.BUILD). Bot uses .scripts/release.sh to create tags; database auto-generates CalVer on main merge.
• Branching: Feature branches → main. PRs reviewed before merge.
• Docker images: Published to manticorum67/major-domo-* and manticorum67/sba-website on Docker Hub.
• Testing: python -m pytest in each sub-project. Factory data preferred over mocks.
• Auth: Bot authenticates to API via API_TOKEN env var, API validates via OAuth2PasswordBearer.
• Reusable Actions: CI pipelines use cal/gitea-actions for calver, docker-tags, gitea-tag, discord-notify.

Which Repo Do I Change?

I want to...	Change this
Add/modify API endpoints	database/
Add/modify bot commands	discord-app-v2/
Change the website	sba-website/
Add a new transaction type	discord-app-v2/ (command + service) + database/ (endpoint + model)
Update league constants (season, weeks)	discord-app-v2/ (config.py) + sba-website/ (utilities.ts)
Deploy the bot	discord-app-v2/.scripts/release.sh → CI builds → ssh akamai pull + restart
Deploy the API	Push to main → CI builds → ssh akamai pull + restart
Deploy the website	sba-website/scripts/build-and-push.sh → ssh akamai pull + restart

Commands

# Discord Bot v2
cd discord-app-v2 && python -m pytest --tb=short -q

# Database API
cd database && python -m pytest --tb=short -q

# Website
cd sba-website && npm run dev
cd sba-website && npm run build

Key Patterns

• Bot commands: Always use @logged_command() decorator + self.logger in __init__
• Models: Database entities require id fields — tests must provide id values
• Data flow: Bot → Database API via HTTP (api/client.py), Website → API via service layer
• League constants: Season 12 (SBA). 18 weeks, 4 games/week.
• Caching: Optional Redis — decorators in utils/decorators.py: @cached_api_call, @cached_single_item, @cache_invalidate

Knowledge Base

Major Domo has a searchable knowledge base for release notes, session summaries, troubleshooting entries, and project documentation.

• Search: Use the kb-search MCP server — mcp__kb-search__search with domain: "major-domo"
• Save new docs: Use the /save-doc skill (sub-commands: save, release-notes, session, troubleshooting)
• Domain: major-domo
• Tags: major-domo, database, deployment, release-notes, discord, etc.

Always check the KB before investigating issues that may have been solved before.

Specialized Agents

Use these agents when working on specific sub-projects:

Agent	Model	Domain	When to Use
md-database	Opus	Database API	Schema changes, migrations, endpoints, service layer
md-discord	Opus	Discord bot	Commands, UX flows, services, background tasks
md-league	Opus	League strategy	Season ops, feature priorities, roadmap, cross-project coordination
md-ops	Sonnet	Release ops	Merging PRs, deploys, branch cleanup, process enforcement
md-database-coder	Sonnet	Database API	Write code: endpoints, models, services, migrations, tests

PO agents (Opus) decide what to build. md-ops (Sonnet) ensures it ships correctly — reviewed, tested, deployed in order. Implementation is delegated to dedicated coders (md-database-coder), engineer, issue-worker, or swarm-coder agents.

When to Use Which Agent

• Design question about an API endpoint or schema → md-database
• Design question about a bot command or UX flow → md-discord
• "Should we build X?" or cross-project feature planning → md-league
• Merge a PR, deploy, tag a release, clean up branches → md-ops
• Write database API code → md-database-coder (preferred for database work)
• Write other code → engineer or swarm-coder

Product Lenses

Work is organized by league impact:

• Operations: Season lifecycle, transaction reliability, commissioner tools
• Experience: Command usability, mobile-friendly interactions, response times
• Growth: Website features, gameplay simulation, draft modernization, external integrations

See ROADMAP.md for the current product roadmap.