# 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

```bash
# 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.