# 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 | ✅ 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

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
- **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