f9d5494615
Reorganize as an umbrella directory managing independent sub-project repos (discord-app-v2, database, sba-website). Adds umbrella CLAUDE.md with architecture diagram and deployment topology, .gitignore for sub-projects, and skeleton ROADMAP.md. Legacy files archived, old website and root docker-compose removed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
120 lines
6.1 KiB
Markdown
120 lines
6.1 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.
|