strat-gameplay-webapp/.claude/implementation/00-index.md

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	✅ Complete	1-2	Connection manager, manual outcome handlers
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, FLYOUT_A/B/BQ/C)
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
Runner Advancement	✅ Complete	2	Unified system for groundballs AND flyballs
Strategic Decisions	✅ Complete	2	DefensiveDecision, OffensiveDecision with validators
Result Charts	✅ Complete	2	PdAutoResultChart, ManualResultChart
WebSocket Manual Mode	✅ Complete	2	roll_dice, submit_manual_outcome events
Terminal Client	✅ Complete	2	Full REPL with manual outcome testing
Comprehensive Docs	✅ Complete	2	8,799 lines of CLAUDE.md across all subdirectories
Substitutions	🔲 Not Started	3	Lineup model supports, logic pending
Pitching Changes	🔲 Not Started	3	Fatigue tracking planned
AI Opponent	🟡 Stub	3	Basic stub exists, needs implementation
Spectator Mode	🔲 Not Started	4	-
UI Polish	🔲 Not Started	4	-
Testing Suite	✅ Complete	2	~540 tests passing (Phase 2 complete)
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 - 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
• 2025-10-31: PHASE 2 COMPLETE - All Week 7 tasks + additional polish
  • Strategic decision system fully integrated
  • Runner advancement unified for groundballs AND flyballs
  • FLYOUT_BQ variant added (4 flyball types total)
  • Result charts complete (PdAutoResultChart, ManualResultChart)
  • WebSocket manual outcome handlers implemented
  • Terminal client with full REPL and manual testing
  • 8,799 lines of comprehensive CLAUDE.md documentation
  • ManualOutcomeSubmission refactored to use PlayOutcome enum
  • All tests updated and passing (~540 total tests)
  • Phase 2 merged to main via PR #1
• 2025-11-03: Created implementation-phase-3 branch - Ready for Week 8

---

Last Updated: 2025-11-03 Phase: Phase 3 - Complete Game Features (Ready to Begin) Current Branch: implementation-phase-3 Current Work: Updating documentation to reflect Phase 2 completion Next Session: Week 8 - Player substitutions and pitching changes Next Milestone: Week 8 completion - Substitution system + pitching management