88a5207c2c
Major reduction in CLAUDE.md file sizes to follow concise documentation standard: | File | Before | After | Reduction | |------|--------|-------|-----------| | backend/CLAUDE.md | 2,467 | 123 | 95% | | models/CLAUDE.md | 1,586 | 102 | 94% | | websocket/CLAUDE.md | 2,094 | 119 | 94% | | config/CLAUDE.md | 1,017 | 126 | 88% | | database/CLAUDE.md | 946 | 130 | 86% | | api/CLAUDE.md | 906 | 140 | 85% | Total: 9,016 -> 740 lines (92% reduction) All files now under 150 lines with: - Essential patterns and usage - Cross-references to related docs - Quick-start examples - Updated timestamps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
# Backend - Paper Dynasty Game Engine
|
|
|
|
## Overview
|
|
|
|
FastAPI-based real-time game backend handling WebSocket communication, game state management, and database persistence for both SBA and PD leagues.
|
|
|
|
**Tech Stack**: FastAPI (Python 3.13), Socket.io, PostgreSQL 14+, SQLAlchemy 2.0, Pydantic v2, pytest
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
backend/
|
|
├── app/
|
|
│ ├── main.py # FastAPI + Socket.io init
|
|
│ ├── config.py # pydantic-settings
|
|
│ ├── core/ # Game engine - see core/CLAUDE.md
|
|
│ ├── config/ # League configs - see config/CLAUDE.md
|
|
│ ├── models/ # Pydantic + SQLAlchemy - see models/CLAUDE.md
|
|
│ ├── websocket/ # Socket.io handlers - see websocket/CLAUDE.md
|
|
│ ├── api/ # REST endpoints - see api/CLAUDE.md
|
|
│ ├── database/ # Async persistence - see database/CLAUDE.md
|
|
│ ├── services/ # Business logic (LineupService, PD API client)
|
|
│ └── utils/ # Logging, auth - see utils/CLAUDE.md
|
|
├── tests/ # See tests/CLAUDE.md
|
|
├── terminal_client/ # Interactive testing - see terminal_client/CLAUDE.md
|
|
└── logs/ # Daily rotating logs (gitignored)
|
|
```
|
|
|
|
## Development
|
|
|
|
### Quick Start
|
|
```bash
|
|
cd backend
|
|
uv sync # Install dependencies
|
|
docker compose up -d # Start Redis
|
|
uv run python -m app.main # Start server at localhost:8000
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
uv run pytest tests/unit/ -v # All unit tests (739 passing)
|
|
uv run python -m terminal_client # Interactive REPL
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
uv run mypy app/ # Type checking
|
|
uv run black app/ # Formatting
|
|
uv run flake8 app/ # Linting
|
|
```
|
|
|
|
## Key Patterns
|
|
|
|
### Hybrid State Management
|
|
- **In-memory**: Active game states for <500ms response
|
|
- **PostgreSQL**: Persistent storage for recovery
|
|
- **Pattern**: Write-through cache (update memory + async DB write)
|
|
|
|
### League-Agnostic Core
|
|
- Game engine works for any league
|
|
- Config-driven behavior (SbaConfig, PdConfig)
|
|
- Polymorphic player models (BasePlayer → SbaPlayer, PdPlayer)
|
|
|
|
### DateTime
|
|
**Always use Pendulum** (never Python's datetime):
|
|
```python
|
|
import pendulum
|
|
now = pendulum.now('UTC')
|
|
```
|
|
|
|
## Environment
|
|
|
|
### Database
|
|
- **Server**: PostgreSQL at 10.10.0.42:5432
|
|
- **Database**: paperdynasty_dev
|
|
- **Connection**: `postgresql+asyncpg://...`
|
|
|
|
### Required .env Variables
|
|
```bash
|
|
DATABASE_URL=postgresql+asyncpg://...
|
|
SECRET_KEY=your-secret-key
|
|
DISCORD_CLIENT_ID=...
|
|
DISCORD_CLIENT_SECRET=...
|
|
```
|
|
|
|
### Python Environment
|
|
- **Version**: Python 3.13.3
|
|
- **Package Manager**: UV (fast, reliable)
|
|
- **Virtual Environment**: `backend/.venv/`
|
|
|
|
## Testing Policy
|
|
|
|
**REQUIRED**: 100% unit tests passing before any commit
|
|
```bash
|
|
uv run pytest tests/unit/ -q # Must show all passing
|
|
```
|
|
|
|
## Coding Standards
|
|
|
|
- **Formatting**: Black (88 chars)
|
|
- **Type Hints**: Required for public functions
|
|
- **Logging**: `logger = logging.getLogger(f'{__name__}.ClassName')`
|
|
- **Error Handling**: "Raise or Return" - no silent failures
|
|
|
|
## Performance Targets
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| Action response | < 500ms |
|
|
| WebSocket delivery | < 200ms |
|
|
| DB writes | < 100ms (async) |
|
|
| State recovery | < 2 seconds |
|
|
|
|
## References
|
|
|
|
- **Type Checking Guide**: `.claude/type-checking-guide.md`
|
|
- **Code Review**: `.claude/CODE_REVIEW_GAME_ENGINE.md`
|
|
- **Implementation Plans**: `../.claude/implementation/`
|
|
- **Full PRD**: `../prd-web-scorecard-1.1.md`
|
|
|
|
---
|
|
|
|
**Tests**: 739/739 passing | **Phase**: 3E-Final Complete | **Updated**: 2025-01-19
|