strat-gameplay-webapp/CLAUDE.md

🚨 CRITICAL: @ MENTION HANDLING 🚨

When ANY file is mentioned with @ syntax, you MUST IMMEDIATELY call Read tool on that file BEFORE responding. You will see automatic loads of any @ mentioned filed, this is NOT ENOUGH, it only loads the file contents. You MUST perform Read tool calls on the files directly, even if they were @ included. This is NOT optional - it loads required CLAUDE.md context. along the file path. See @./.claude/force-claude-reads.md for details.

---

Paper Dynasty Real-Time Game Engine - Development Guide

Project Overview

Web-based real-time multiplayer baseball simulation platform replacing legacy Google Sheets system. Consists of:

• Shared Backend: FastAPI (Python 3.11+) with WebSocket support, PostgreSQL persistence
• Dual Frontends: Separate Vue 3/Nuxt 3 apps per league (SBA and PD) with shared component library

Critical Business Driver: Legacy Google Sheets being deprecated - this is mission-critical replacement.

Architecture Principles

Backend Philosophy

• Hybrid State Model: In-memory game state for performance + PostgreSQL for persistence/recovery
• League-Agnostic Core: Polymorphic player models, config-driven league variations
• Async-First: All I/O operations use async/await patterns
• Type Safety: Pydantic models for validation, SQLAlchemy for ORM

Frontend Philosophy

• Mobile-First: Primary design target is mobile portrait mode
• Real-Time Updates: WebSocket (Socket.io) for all game state changes
• Shared Components: Maximize reuse between league frontends
• Type Safety: TypeScript with strict mode

Technology Stack

Backend

• FastAPI + Socket.io (WebSocket)
• PostgreSQL 14+ with SQLAlchemy 2.0
• Pydantic for data validation
• pytest for testing

Frontend (Per League)

• Vue 3 Composition API + Nuxt 3
• TypeScript (strict mode)
• Tailwind CSS
• Pinia for state management
• Socket.io-client
• Discord OAuth via HttpOnly cookies (see COOKIE_AUTH_IMPLEMENTATION.md)

Key Technical Patterns

Polymorphic Player Architecture

Use factory pattern for league-specific player types:

• BasePlayer (abstract base)
• SbaPlayer (simple model)
• PdPlayer (detailed scouting data)
• Lineup.from_api_data(config, data) factory method

WebSocket Event Flow

1. Player action → WebSocket → Backend
2. Validate against in-memory state
3. Process + resolve outcome
4. Update in-memory state
5. Async write to PostgreSQL
6. Broadcast state update to all clients

Game State Recovery

On reconnect: Load plays from DB → Replay to rebuild state → Send current state

Project Structure

strat-gameplay-webapp/
├── backend/              # FastAPI game engine
│   ├── app/
│   │   ├── core/         # Game engine, dice, state management
│   │   ├── config/       # League configs and result charts
│   │   ├── websocket/    # Socket.io handlers
│   │   ├── models/       # Pydantic + SQLAlchemy models
│   │   └── api/          # REST endpoints
│   └── tests/
├── frontend-sba/         # SBA League Nuxt app
├── frontend-pd/          # PD League Nuxt app
├── docker-compose.yml    # Dev orchestration (all services)
├── docker-compose.prod.yml # Production overrides
└── .env.example          # Root environment template

Environment Configuration

Multi-Domain Support

The project is fully environment-driven for deployment to different domains. All URLs and credentials are externalized.

Environment Files

File	Purpose
.env.example	Root template - copy to .env
backend/.env.example	Backend-specific template
frontend-sba/.env.example	SBA frontend template
frontend-pd/.env.example	PD frontend template

Key Environment Variables

Backend (in backend/.env):

• DATABASE_URL - PostgreSQL connection string
• DISCORD_CLIENT_ID/SECRET - OAuth credentials
• DISCORD_SERVER_REDIRECT_URI - Server-side OAuth callback
• FRONTEND_URL - Frontend base URL for redirects
• CORS_ORIGINS - Allowed origins (comma-separated)
• ALLOWED_DISCORD_IDS - User whitelist (comma-separated, empty = all)

Frontend (in frontend-*/env):

• NUXT_PUBLIC_API_URL - Backend API URL
• NUXT_PUBLIC_WS_URL - WebSocket URL
• NUXT_PUBLIC_DISCORD_CLIENT_ID - OAuth client ID (public)
• NUXT_PUBLIC_DISCORD_REDIRECT_URI - OAuth callback URL
• NUXT_ALLOWED_HOSTS - Vite dev server allowed hosts (comma-separated)

Docker Deployment

# Development
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

See README.md "Multi-Domain Deployment" section for full checklist.

Development Guidelines

Code Quality

• Python: Dataclasses preferred, rotating loggers with f'{__name__}.<className>'
• Error Handling: "Raise or Return" pattern - no Optional unless required
• Testing: Run tests freely without asking permission
• Imports: Always verify imports during code review to prevent NameErrors
• Git Commits: Prefix with "CLAUDE: "

Performance Targets

• Action response: < 500ms
• WebSocket delivery: < 200ms
• DB writes: < 100ms (async)
• State recovery: < 2 seconds

Security Requirements

• Discord OAuth for authentication
• Server-side game logic only (zero client trust)
• Cryptographically secure dice rolls
• All rules enforced server-side

Phase 1 MVP Scope (Weeks 1-13)

Core Deliverables:

1. Authentication (Discord OAuth)
2. Game creation & lobby
3. Complete turn-based gameplay with all strategic decisions
4. Real-time WebSocket updates
5. Game persistence & recovery
6. Spectator mode
7. Mobile-optimized UI
8. AI opponent support

Explicitly Out of Scope for MVP:

• Roster management
• Marketplace
• Tournaments
• Advanced analytics

Critical References

• Full PRD: /mnt/NV2/Development/strat-gameplay-webapp/prd-web-scorecard-1.1.md
• Player Model Architecture: PRD lines 378-551
• Database Schema: PRD lines 553-628
• WebSocket Events: PRD lines 630-669
• League Config System: PRD lines 780-846

League Differences

SBA League

• Minimal player data (id, name, image)
• Simpler rules configuration

PD League

• Detailed scouting data on players
• Complex probability calculations
• Additional analytics requirements

Success Metrics

• 90% player migration within 1 month
• 99.5% uptime
• < 500ms average action latency
• 60%+ mobile usage
• Zero data corruption

---

Current Implementation Status

Phase 3E-Final: ✅ COMPLETE (2025-01-10)

Backend is production-ready for frontend integration:

• ✅ All 15 WebSocket event handlers implemented
• ✅ Strategic decisions (defensive/offensive)
• ✅ Manual outcome workflow (dice rolling + card reading)
• ✅ Player substitutions (3 types)
• ✅ Box score statistics (materialized views)
• ✅ Position ratings integration (PD league)
• ✅ 730/731 tests passing (99.9%)

Next Phase: Vue 3 + Nuxt 3 frontend implementation with Socket.io client

---

Note: Subdirectories have their own CLAUDE.md files with implementation-specific details to minimize context usage.