major-domo-database/CLAUDE.md

Major Domo Database API

FastAPI backend serving SBA fantasy league data. Peewee ORM with PostgreSQL.

Architecture

• Routers: Domain-based in app/routers_v3/ under /api/v3/ prefix
• ORM: Peewee — always specify Meta.table_name to match PostgreSQL naming
• Auth: OAuth2 bearer token via API_TOKEN env var
• Error handling: @handle_db_errors decorator (logging, rollback, HTTP errors)
• POST models: Use Optional[int] = None for id fields (DB auto-generates)
• Logging: Rotating file handler (/tmp/sba-database.log, 8MB max, 5 backups)

Environments & Troubleshooting

	Dev	Prod
Host	10.10.0.42 (ssh sba-db)	ssh akamai → cd container-data/sba-database
API container	dev_sba_db_api	sba_db_api
PostgreSQL	sba_postgres (port 5432)	sba_postgres
Redis	sba_redis (port 6379)	sba_redis
Adminer	port 8080	port 8080
API port	801 → 80	801 → 80
Image	manticorum67/major-domo-database:dev-pg	manticorum67/major-domo-database:latest

Commands

docker-compose up                          # Start all services
docker-compose pull && docker-compose up --build  # Pull latest and rebuild
docker-compose --profile sync up sync-prod # One-time production data sync

Logs

• Container logs: docker logs --since 1h sba_db_api
• Log file (in container): /usr/src/app/logs/sba-database.log (rotating, 8MB, 5 backups)
• Health check: GET /api/v3/current (curl built into Dockerfile healthcheck)

Common Issues

• 500 errors → check docker logs sba_db_api, look for Peewee/PostgreSQL connection errors
• Stale data → Redis cache; clear with docker exec sba_redis redis-cli FLUSHDB
• DB connection pool exhausted → restart API container (pool: 20 connections, 5min stale timeout)
• CI/CD: Gitea Actions on PR to main — builds Docker image, auto-generates CalVer version (YYYY.MM.BUILD) on merge

Important

• All active code is in /app — root-level main.py, db_engine.py are legacy, not in use
• PostgreSQL only (no SQLite fallback)
• Migrations are SQL files in migrations/, applied manually via psql
• API docs auto-generated at /api/docs
• NEVER run or test against the local docker compose — always deploy to and test against the dev server (10.10.0.42:814). The local container has no meaningful data.