3359d2fc19
- md-database, md-discord, md-league, md-ops agents defined in .claude/agents/ - "When to Use Which Agent" guide for routing decisions - Product lenses section (Operations, Experience, Growth) - ROADMAP.md skeleton with future considerations Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
7.6 KiB
Markdown
151 lines
7.6 KiB
Markdown
# 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 |
|
|
|
|
PO agents (Opus) decide **what** to build. `md-ops` (Sonnet) ensures it **ships correctly** — reviewed, tested, deployed in order. Implementation is delegated to `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 code** to implement a spec → `engineer` or `swarm-coder` (not the PO agents)
|
|
|
|
## 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.
|