paper-dynasty-database/CLAUDE.md

Paper Dynasty Database API

FastAPI backend for baseball card game data. Peewee ORM with SQLite (WAL mode).

Commands

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000  # Dev server
python main.py                                              # Alt start
python db_migrations.py                                     # Run migrations
docker build -t paper-dynasty-db .                          # Build image

Architecture

• Routers: Domain-based in app/routers_v2/ (cards, players, teams, packs, stats, gauntlets, scouting)
• ORM: Peewee with SQLite (storage/pd_master.db, WAL journaling)
• Card images: Playwright/Chromium renders HTML templates → screenshots (see routers_v2/players.py)
• Logging: Rotating files in logs/database/{date}.log

Key Constants

• LIVE_CARDSET_ID: 24 (current active cardset, in db_engine.py)
• ranked_cardsets: Legal cardsets for ranked play
• CARDSETS: Configuration for game modes and card availability

Environments & Troubleshooting

	Dev	Prod
URL	pddev.manticorum.com	pd.manticorum.com
Host	ssh pd-database	ssh akamai → /root/container-data/paper-dynasty
API container	dev_pd_database	pd_api
PostgreSQL	pd_postgres (port 5432)	pd_postgres
Adminer	port 8081	—
API port	816	815
Image	manticorum67/paper-dynasty-database	manticorum67/paper-dynasty-database

Logs

• Container logs: docker logs --since 1h pd_api
• Log file (in container): logs/database/YYYY-MM-DD.log (date-stamped daily, no rotation)
• API docs: /api/docs and /api/redoc

Key Env Vars

API_TOKEN, LOG_LEVEL, DATABASE_TYPE (sqlite/postgresql), POSTGRES_HOST, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

Common Issues

• 502 Bad Gateway → API container crashed; check docker logs pd_api
• Card image generation failures → Playwright/Chromium issue; check for missing dependencies
• SQLite locking (dev) → WAL mode should prevent, but check for long-running writes
• DB connection errors → verify POSTGRES_HOST points to correct container name
• CI/CD: Gitea Actions on PR to main — builds Docker image, auto-generates CalVer version (YYYY.MM.BUILD) on merge

Release Workflow

1. Create feature/fix branches off next-release (e.g., fix/card-pricing)
2. When done, merge the branch into next-release — this is the staging branch where changes accumulate
3. When ready to release, open a PR from next-release → main
4. CI builds Docker image on PR; CalVer tag is created on merge
5. Deploy the new image to production

Important

• Docker image installs only Playwright Chromium (not all browsers) to optimize size
• Teams have dynamic card pricing based on market activity
• Supports both human players and AI teams
• Gauntlet events use special reward structures and card pools