Cal Corum f9d5494615 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) <noreply@anthropic.com>

2026-03-24 01:14:05 -05:00

6.1 KiB

Raw Blame History

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.

6.1 KiB Raw Blame History