a4b99ee53e
Migrated to ruff for faster, modern code formatting and linting: Configuration changes: - pyproject.toml: Added ruff 0.8.6, removed black/flake8 - Configured ruff with black-compatible formatting (88 chars) - Enabled comprehensive linting rules (pycodestyle, pyflakes, isort, pyupgrade, bugbear, comprehensions, simplify, return) - Updated CLAUDE.md: Changed code quality commands to use ruff Code improvements (490 auto-fixes): - Modernized type hints: List[T] → list[T], Dict[K,V] → dict[K,V], Optional[T] → T | None - Sorted all imports (isort integration) - Removed unused imports - Fixed whitespace issues - Reformatted 38 files for consistency Bug fixes: - app/core/play_resolver.py: Fixed type hint bug (any → Any) - tests/unit/core/test_runner_advancement.py: Removed obsolete random mock Testing: - All 739 unit tests passing (100%) - No regressions introduced 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
125 lines
3.6 KiB
Markdown
125 lines
3.6 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 ruff check app/ # Linting
|
|
uv run ruff format app/ # Formatting
|
|
```
|
|
|
|
## 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**: Ruff (88 chars, black-compatible)
|
|
- **Linting**: Ruff (replaces flake8, includes isort, pyupgrade)
|
|
- **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
|