# Paper Dynasty Database API

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

## Commands

```bash
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