880adb315e
Remove duplicated user-level rules, README-level Docker/env docs, MVP scope, success metrics, and implementation status. Keep stack, commands, architecture, and code quality rules. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
63 lines
2.1 KiB
Markdown
63 lines
2.1 KiB
Markdown
# 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
|