# Paper Dynasty Real-Time Game Engine

Web-based real-time multiplayer baseball simulation replacing legacy Google Sheets.

## Stack

- **Backend**: FastAPI + Socket.io, PostgreSQL, Python 3.11+, Pydantic, SQLAlchemy 2.0
- **Frontend**: Vue 3 + Nuxt 3, TypeScript strict, Tailwind CSS, Pinia, Socket.io-client
- **Auth**: Discord OAuth via HttpOnly cookies (see `COOKIE_AUTH_IMPLEMENTATION.md`)

## Commands

```bash
# Native development (recommended)
./dev-native.sh start    # Start all services
./dev-native.sh logs     # View logs
./dev-native.sh stop     # Stop

# Docker (production builds only — dev mode auth is broken)
./start.sh prod          # Production mode
./start.sh stop          # Stop all

# Environment switching
./scripts/env-switch.sh dev|prod  # Copy .env.{profile} → .env
```

## Architecture

### Hybrid State Model
- In-memory game state for performance + PostgreSQL for persistence/recovery
- On reconnect: Load plays from DB → replay to rebuild state → send current state

### Polymorphic Players
- `BasePlayer` (abstract) → `SbaPlayer` (simple) / `PdPlayer` (detailed scouting)
- Factory: `Lineup.from_api_data(config, data)`

### WebSocket Flow
Player action → WebSocket → validate against in-memory state → process → async DB write → broadcast to clients

## Code Quality
- Python: Dataclasses preferred, rotating loggers with `f'{__name__}.<className>'`
- Error handling: "Raise or Return" pattern — no Optional unless required
- Git commits: Prefix with "CLAUDE: "
- Security: Zero client trust, server-side logic only, cryptographically secure dice

## Key URLs

| Service | Dev | Prod |
|---------|-----|------|
| Frontend | http://localhost:3000 | https://gameplay-demo.manticorum.com |
| Backend API | http://localhost:8000 | https://gameplay-demo.manticorum.com/api |

## League Differences

- **SBA**: Minimal player data (id, name, image), simpler rules
- **PD**: Detailed scouting data, complex probability calculations

## References

- **Full PRD**: `prd-web-scorecard-1.1.md`
- **Native dev setup**: `NATIVE_DEV_SETUP.md`
- Subdirectories have their own CLAUDE.md files for implementation details