f3238c4e6d
Add comprehensive unit and integration tests for Week 5 deliverables: - test_play_resolver.py: 18 tests covering outcome resolution and runner advancement - test_validators.py: 36 tests covering game state, decisions, lineups, and flow - test_game_engine.py: 7 test classes for complete game flow integration Update implementation documentation to reflect completed status: - 00-index.md: Mark Phase 2 Weeks 4-5 complete with test coverage - 02-week5-game-logic.md: Comprehensive test details and completion status - 02-game-engine.md: Forward-looking snapshot pattern documentation Week 5 now fully complete with 54 unit tests + 7 integration test classes passing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
6.6 KiB
6.6 KiB
Paper Dynasty Real-Time Game Engine - Implementation Guide
Table of Contents
Architecture & Design
- Backend Architecture - FastAPI structure, game engine, state management
- Frontend Architecture - Vue/Nuxt structure, shared components, league-specific apps
- Database Design - Schema, indexes, operations, migration strategy
- WebSocket Protocol - Event specifications, connection lifecycle, error handling
Implementation Phases
Phase 1: Core Infrastructure (Weeks 1-3)
- 01 - Infrastructure Setup
- Backend foundation (FastAPI, PostgreSQL, Socket.io)
- Frontend foundation (Nuxt 3, TypeScript, Tailwind)
- Discord OAuth integration
- WebSocket connection management
- Basic session management
Phase 2: Game Engine Core (Weeks 4-6)
- 02 - Game Engine
- In-memory game state management
- Play resolution engine
- League configuration system
- Polymorphic player models
- Database persistence layer
- State recovery mechanism
Phase 3: Complete Game Features (Weeks 7-9)
- 03 - Gameplay Features
- All strategic decision types
- Substitution system
- Pitching changes
- Complete result charts (both leagues)
- AI opponent integration
- Async game mode support
Phase 4: Spectator & Polish (Weeks 10-11)
- 04 - Spectator & Polish
- Spectator mode implementation
- UI/UX refinements
- Dice roll animations
- Mobile touch optimization
- Accessibility improvements
- Performance optimization
Phase 5: Testing & Launch (Weeks 12-13)
- 05 - Testing & Launch
- Comprehensive testing strategy
- Load testing procedures
- Security audit checklist
- Deployment procedures
- Monitoring setup
- Launch plan
Cross-Cutting Concerns
- Authentication & Authorization - Discord OAuth, session management, role-based access
- Testing Strategy - Unit, integration, e2e, load testing approaches
- Deployment Guide - Infrastructure setup, CI/CD, monitoring
- API Reference - REST endpoints, request/response formats
Implementation Status
| Component | Status | Phase | Notes |
|---|---|---|---|
| Backend Foundation | ✅ Complete | 1 | FastAPI, PostgreSQL, async session management |
| Frontend Foundation | 🔲 Not Started | 1 | Nuxt 3 apps pending |
| Discord OAuth | 🔲 Not Started | 1 | Auth system pending |
| WebSocket Server | 🟡 Partial | 1 | Connection manager exists, handlers pending |
| Game Engine Core | ✅ Complete | 2 | GameEngine with forward-looking snapshots, missing some tests |
| Database Schema | ✅ Complete | 2 | All tables created, polymorphic models working |
| Player Models | ✅ Complete | 2 | Polymorphic Lineup & RosterLink for PD/SBA |
| Strategic Decisions | 🔲 Not Started | 3 | Basic framework exists in decisions models |
| Substitutions | 🔲 Not Started | 3 | Lineup model supports, logic pending |
| AI Opponent | 🔲 Not Started | 3 | - |
| Spectator Mode | 🔲 Not Started | 4 | - |
| UI Polish | 🔲 Not Started | 4 | - |
| Testing Suite | 🟡 Partial | 5 | Unit tests for dice/state, integration tests missing |
| Deployment | 🔲 Not Started | 5 | - |
Quick Start
- Review Architecture Documents - Understand the system design before coding
- Follow Phase Order - Each phase builds on the previous
- Update Status - Keep the status table current as work progresses
- Reference PRD - Main PRD at
/prd-web-scorecard-1.1.mdfor detailed requirements
Key Decisions & Rationale
Why Hybrid State Management?
- In-Memory: Fast action processing, sub-500ms latency requirements
- PostgreSQL: Persistence, recovery, play history, async operations
- Best of Both: Performance without sacrificing reliability
Why Separate Frontends?
- League Branding: Each league maintains distinct identity
- Independent Deployment: Can update one league without affecting other
- Shared Components: 80%+ code reuse through component library
- Flexibility: League-specific features without codebase pollution
Why FastAPI + Socket.io?
- FastAPI: Modern async Python, automatic OpenAPI docs, Pydantic validation
- Socket.io: Mature WebSocket library, automatic reconnection, room support
- Python Ecosystem: Rich data processing libraries for game logic
Why Polymorphic Players?
- Type Safety: Each league's player structure validated at runtime
- Maintainability: League differences isolated in player classes
- Extensibility: Easy to add new leagues or modify existing ones
Critical Path Items
Must Have for MVP
- ✅ Game creation and lobby
- ✅ Complete turn-based gameplay
- ✅ Real-time WebSocket updates
- ✅ Game persistence and recovery
- ✅ Mobile-optimized UI
- ✅ Discord authentication
Nice to Have (Post-MVP)
- 🔲 Roster management
- 🔲 Marketplace
- 🔲 Tournament system
- 🔲 Advanced analytics
- 🔲 Discord bot notifications
Development Workflow
- Start Phase - Read phase markdown file thoroughly
- Create CLAUDE.md - Add subdirectory-specific context
- Implement - Follow TDD where appropriate
- Test - Unit tests as you go, integration tests per milestone
- Update Status - Mark components complete in index
- Review - Check against PRD requirements before moving on
Performance Budgets
| Metric | Target | Critical Threshold |
|---|---|---|
| Action Response | < 500ms | < 1000ms |
| WebSocket Delivery | < 200ms | < 500ms |
| DB Write (async) | < 100ms | < 250ms |
| State Recovery | < 2s | < 5s |
| Page Load (3G) | < 3s | < 5s |
Questions & Decisions Log
Track important decisions and open questions here as implementation progresses.
Open Questions
- Which VPS provider for deployment?
- Specific Discord OAuth scope requirements?
- AI opponent complexity level for MVP?
- Spectator chat feature in MVP or post-MVP?
Decisions Made
- 2025-10-21: Project initialized, implementation guide structure created
- 2025-10-22: Week 4 complete - State management and persistence working
- 2025-10-24: Week 5 complete - Game engine core with AbRoll dice system
- 2025-10-25: GameEngine refactored to forward-looking play tracking pattern
Last Updated: 2025-10-25 Phase: Phase 2 - Week 5 Complete (Game Logic) Next Milestone: Phase 2 - Week 6 (League Features & Integration) OR Phase 3 (Complete Game Features)