64aa800672
Updated week 6 status and created comprehensive next session plan. ## Changes ### Implementation Status Updates - Updated 00-index.md with Week 6 progress (75% complete) - Updated 02-week6-league-features.md status and goals - Added new components to status table: - League Configs: ✅ Complete - PlayOutcome Enum: ✅ Complete - PlayResolver Integration: 🟡 Partial ### Next Session Plan (NEW) Created NEXT_SESSION.md with detailed task breakdown: **Task 1: Update Dice System** (30 min) - Rename check_d20 → chaos_d20 - Update docstrings for chaos die purpose - Update all references **Task 2: Integrate PlayOutcome** (60 min) - Replace old local enum with universal enum - Update SimplifiedResultChart - Add uncapped hit handling - Update all outcome references **Task 3: Add Play.metadata** (30 min) - Add JSONB metadata field to Play model - Log uncapped hits in metadata - Update game_engine._save_play_to_db() ## Quick Context for Next Session **What's Complete**: Config system, PlayOutcome enum, 58 tests passing **What's Remaining**: Dice system update, PlayResolver integration, metadata support **Estimated Time**: 2 hours **Success Criteria**: All tests passing, uncapped hits tracked, terminal client works 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
7.2 KiB
7.2 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 |
| Database Schema | ✅ Complete | 2 | All tables created, polymorphic models working |
| Player Models | ✅ Complete | 2 | BasePlayer, SbaPlayer, PdPlayer with ratings |
| League Configs | ✅ Complete | 2 | SbaConfig, PdConfig with immutable settings (Week 6) |
| PlayOutcome Enum | ✅ Complete | 2 | Universal enum for both leagues (Week 6) |
| PlayResolver Integration | 🟡 Partial | 2 | Needs PlayOutcome migration (Week 6 - 75% done) |
| 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 | 58 config tests + existing core/state tests |
| 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
- 2025-10-28: Week 6 - 75% complete - Config system and PlayOutcome enum implemented
- Both SBA and PD use same card-based resolution mechanics
- Universal PlayOutcome enum with helper methods
- Immutable league configs with singleton registry
- 58 config tests, all passing
Last Updated: 2025-10-28 Phase: Phase 2 - Week 6 (75% Complete) Current Work: League configuration and play outcome system Next Session: Complete Week 6 - dice system update and PlayResolver integration Next Milestone: Phase 3 (Complete Game Features) after Week 6 finished