5c75b935f0
Add comprehensive project documentation and Docker infrastructure for Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball simulation platform replacing the legacy Google Sheets system. Documentation Added: - Complete PRD (Product Requirements Document) - Project README with dual development workflows - Implementation guide with 5-phase roadmap - Architecture docs (backend, frontend, database, WebSocket) - CLAUDE.md context files for each major directory Infrastructure Added: - Root docker-compose.yml for full stack orchestration - Dockerfiles for backend and both frontends (multi-stage builds) - .dockerignore files for optimal build context - .env.example with all required configuration - Updated .gitignore for Python, Node, Nuxt, and Docker Project Structure: - backend/ - FastAPI + Socket.io game engine (Python 3.11+) - frontend-sba/ - SBA League Nuxt 3 frontend - frontend-pd/ - PD League Nuxt 3 frontend - .claude/implementation/ - Detailed implementation guides Supports two development workflows: 1. Local dev (recommended): Services run natively with hot-reload 2. Full Docker: One-command stack orchestration for testing/demos Next: Phase 1 implementation (backend/frontend foundations)
5.9 KiB
5.9 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 | Not Started | 1 | - |
| Frontend Foundation | Not Started | 1 | - |
| Discord OAuth | Not Started | 1 | - |
| WebSocket Server | Not Started | 1 | - |
| Game Engine Core | Not Started | 2 | - |
| Database Schema | Not Started | 2 | - |
| Player Models | Not Started | 2 | - |
| Strategic Decisions | Not Started | 3 | - |
| Substitutions | Not Started | 3 | - |
| AI Opponent | Not Started | 3 | - |
| Spectator Mode | Not Started | 4 | - |
| UI Polish | Not Started | 4 | - |
| Testing Suite | Not Started | 5 | - |
| 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
Last Updated: 2025-10-21 Phase: Pre-Implementation Next Milestone: Phase 1 - Core Infrastructure Setup