d7caa75310
Terminal Client Enhancements: - Added list_outcomes command to display all PlayOutcome values - Added resolve_with <outcome> command for testing specific scenarios - TAB completion for all outcome names - Full help documentation and examples - Infrastructure ready for Week 7 integration Files Modified: - terminal_client/commands.py - list_outcomes() and forced outcome support - terminal_client/repl.py - do_list_outcomes() and do_resolve_with() commands - terminal_client/completions.py - VALID_OUTCOMES and complete_resolve_with() - terminal_client/help_text.py - Help entries for new commands Phase 3 Planning: - Created comprehensive Week 7 implementation plan (25 pages) - 6 major tasks covering strategic decisions and result charts - Updated 00-index.md to mark Week 6 as 100% complete - Documented manual outcome testing feature Week 6: 100% Complete ✅ Phase 3 Week 7: Ready to begin 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
7.7 KiB
7.7 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 |
| PlayOutcome Enum | ✅ Complete | 2 | Granular variants (SINGLE_1/2, GROUNDBALL_A/B/C, etc.) |
| PlayResolver Integration | ✅ Complete | 2 | Universal PlayOutcome from app.config, metadata support |
| Dice System | ✅ Complete | 2 | chaos_d20 for WP/PB checks, resolution_d20 for outcomes |
| 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 | 200/201 tests passing (config, core, state, dice) |
| 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 - 100% complete - Config system and PlayOutcome enum implemented
- Both SBA and PD use same card-based resolution mechanics
- Universal PlayOutcome enum with helper methods and granular variants
- Immutable league configs with singleton registry
- Renamed check_d20 → chaos_d20 for clarity
- Added play_metadata support for uncapped hits
- PlayResolver fully integrated with universal PlayOutcome
- 200/201 tests passing (1 pre-existing timing issue)
- 2025-10-29: Phase 3 planning - Ready to implement strategic decisions and result charts
Last Updated: 2025-10-29 Phase: Phase 3 - Complete Game Features (Planning) Current Work: Phase 3 planning and strategic decision system design Next Session: Week 7 - Strategic decisions and complete result charts Next Milestone: Week 7 completion - All decision types + full result charts