From f9d5494615876280599984ff0eedb89fcb1665be Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Tue, 24 Mar 2026 01:14:05 -0500 Subject: [PATCH] Initialize Major Domo umbrella repo 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) --- .gitignore | 17 ++++++++ CLAUDE.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 37 +++++++++++++++++ 3 files changed, 173 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 ROADMAP.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2163600 --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +# Sub-project repositories (independent git repos) +discord-app-v2/ +database/ +sba-website/ + +# Development mounts +dev-storage/ +dev-logs/ + +# Claude Code config (machine-specific) +.claude/ + +# Archive +.archive/ + +# OS +.DS_Store diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5bc6c02 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,119 @@ +# 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. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..f524400 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,37 @@ +# Major Domo — Roadmap + +> Last updated: 2026-03-23 + +## Current State + +Major Domo manages the SBA (Strat-o-Matic Baseball Association) fantasy baseball league through a Discord bot, FastAPI database API, and Vue.js website. The system handles team rosters, player transactions, trades, dice rolling, standings, schedules, and game results. + +**Bot**: v2.29.9 — mature, full slash command coverage +**Database API**: v2.7.0 — stable, PostgreSQL-backed +**Website**: v2.1.1 — functional, covers core league info + +--- + +## Roadmap + + + +### In Progress + + +### Near Term + + +### Future Considerations + +- Gameplay simulation (migrated from legacy bot v1 — currently not in v2) +- Draft system (automated draft room — currently handled externally) +- Player comparison command +- Website CI/CD pipeline (currently manual build/push) +- Historical records and awards pages + +--- + +## Completed + +