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)
166 lines
5.9 KiB
Markdown
166 lines
5.9 KiB
Markdown
# Paper Dynasty Real-Time Game Engine - Implementation Guide
|
|
|
|
## Table of Contents
|
|
|
|
### Architecture & Design
|
|
- [Backend Architecture](./backend-architecture.md) - FastAPI structure, game engine, state management
|
|
- [Frontend Architecture](./frontend-architecture.md) - Vue/Nuxt structure, shared components, league-specific apps
|
|
- [Database Design](./database-design.md) - Schema, indexes, operations, migration strategy
|
|
- [WebSocket Protocol](./websocket-protocol.md) - Event specifications, connection lifecycle, error handling
|
|
|
|
### Implementation Phases
|
|
|
|
#### Phase 1: Core Infrastructure (Weeks 1-3)
|
|
- [01 - Infrastructure Setup](./01-infrastructure.md)
|
|
- 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](./02-game-engine.md)
|
|
- 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](./03-gameplay-features.md)
|
|
- 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](./04-spectator-polish.md)
|
|
- 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](./05-testing-launch.md)
|
|
- Comprehensive testing strategy
|
|
- Load testing procedures
|
|
- Security audit checklist
|
|
- Deployment procedures
|
|
- Monitoring setup
|
|
- Launch plan
|
|
|
|
### Cross-Cutting Concerns
|
|
- [Authentication & Authorization](./auth-system.md) - Discord OAuth, session management, role-based access
|
|
- [Testing Strategy](./testing-strategy.md) - Unit, integration, e2e, load testing approaches
|
|
- [Deployment Guide](./deployment-guide.md) - Infrastructure setup, CI/CD, monitoring
|
|
- [API Reference](./api-reference.md) - 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
|
|
|
|
1. **Review Architecture Documents** - Understand the system design before coding
|
|
2. **Follow Phase Order** - Each phase builds on the previous
|
|
3. **Update Status** - Keep the status table current as work progresses
|
|
4. **Reference PRD** - Main PRD at `/prd-web-scorecard-1.1.md` for 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
|
|
|
|
1. **Start Phase** - Read phase markdown file thoroughly
|
|
2. **Create CLAUDE.md** - Add subdirectory-specific context
|
|
3. **Implement** - Follow TDD where appropriate
|
|
4. **Test** - Unit tests as you go, integration tests per milestone
|
|
5. **Update Status** - Mark components complete in index
|
|
6. **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
|