From 880adb315efebf51cbd1ffa08a540298102c9793 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Sat, 14 Feb 2026 08:31:09 -0600 Subject: [PATCH] Optimize CLAUDE.md from 303 to 63 lines Remove duplicated user-level rules, README-level Docker/env docs, MVP scope, success metrics, and implementation status. Keep stack, commands, architecture, and code quality rules. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 318 +++++++----------------------------------------------- 1 file changed, 39 insertions(+), 279 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 278246c..e67cf5a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,302 +1,62 @@ -# 🚨 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 ---- +Web-based real-time multiplayer baseball simulation replacing legacy Google Sheets. -# Paper Dynasty Real-Time Game Engine - Development Guide +## Stack -## Project Overview +- **Backend**: FastAPI + Socket.io, PostgreSQL, Python 3.11+, Pydantic, SQLAlchemy 2.0 +- **Frontend**: Vue 3 + Nuxt 3, TypeScript strict, Tailwind CSS, Pinia, Socket.io-client +- **Auth**: Discord OAuth via HttpOnly cookies (see `COOKIE_AUTH_IMPLEMENTATION.md`) -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 (disabled) -├── docker-compose.yml # Base service configuration -├── docker-compose.dev.yml # Development overrides (hot-reload) -├── docker-compose.prod.yml # Production overrides (optimized) -├── start.sh # Single-command startup script -└── scripts/env-switch.sh # Environment profile switcher -``` - -## Quick Start - -### 🚀 Recommended: Native Development (Fast) - -For day-to-day development, use native mode for instant startup and hot-reload: +## Commands ```bash -# Start everything natively (5-10 seconds, hot-reload enabled) -./dev-native.sh start +# Native development (recommended) +./dev-native.sh start # Start all services +./dev-native.sh logs # View logs +./dev-native.sh stop # Stop -# View logs -./dev-native.sh logs +# Docker (production builds only — dev mode auth is broken) +./start.sh prod # Production mode +./start.sh stop # Stop all -# Stop when done -./dev-native.sh stop +# Environment switching +./scripts/env-switch.sh dev|prod # Copy .env.{profile} → .env ``` -**See [NATIVE_DEV_SETUP.md](NATIVE_DEV_SETUP.md) for full setup instructions.** +## Architecture -### 🐳 Alternative: Docker Workflow +### Hybrid State Model +- In-memory game state for performance + PostgreSQL for persistence/recovery +- On reconnect: Load plays from DB → replay to rebuild state → send current state -For testing production builds or Docker-specific scenarios: +### Polymorphic Players +- `BasePlayer` (abstract) → `SbaPlayer` (simple) / `PdPlayer` (detailed scouting) +- Factory: `Lineup.from_api_data(config, data)` -```bash -# Production (optimized build) -./start.sh prod +### WebSocket Flow +Player action → WebSocket → validate against in-memory state → process → async DB write → broadcast to clients -# Development - DO NOT USE (auth broken) -# ./start.sh dev +## Code Quality +- Python: Dataclasses preferred, rotating loggers with `f'{__name__}.'` +- Error handling: "Raise or Return" pattern — no Optional unless required +- Git commits: Prefix with "CLAUDE: " +- Security: Zero client trust, server-side logic only, cryptographically secure dice -# Stop all services -./start.sh stop +## Key URLs -# View logs -./start.sh logs - -# Check status -./start.sh status - -# Force rebuild -./start.sh rebuild [dev|prod] -``` - -### What Each Mode Does - -| Mode | Backend | Frontend | Use Case | -|------|---------|----------|----------| -| `prod` | Production build | SSR optimized build | **Always use this** - auth works correctly | -| `dev` | Hot-reload (uvicorn --reload) | Hot-reload (nuxt dev) | ❌ Auth broken - do not use | - -### Service URLs - -| Service | Dev Mode | Prod Mode | -|---------|----------|-----------| +| Service | Dev | Prod | +|---------|-----|------| | Frontend | http://localhost:3000 | https://gameplay-demo.manticorum.com | | Backend API | http://localhost:8000 | https://gameplay-demo.manticorum.com/api | -| API Docs | http://localhost:8000/docs | https://gameplay-demo.manticorum.com/api/docs | - -### Docker Compose Architecture - -The stack uses layered compose files: - -- **`docker-compose.yml`** - Base services (Redis, Backend, Frontend-SBA) -- **`docker-compose.dev.yml`** - Development overrides (volume mounts, hot-reload) -- **`docker-compose.prod.yml`** - Production overrides (optimized builds, restart policies) - -The `start.sh` script handles composing these correctly. - -## Environment Configuration - -### Environment Profiles - -| Profile | Backend URL | Frontend URL | -|---------|-------------|--------------| -| `dev` | `http://localhost:8000` | `http://localhost:3000` | -| `prod` | `https://gameplay-demo.manticorum.com` | `https://gameplay-demo.manticorum.com` | - -### Environment Files - -| File | Purpose | -|------|---------| -| `backend/.env` | Active backend config (gitignored) | -| `backend/.env.dev` | Local development settings | -| `backend/.env.prod` | Production settings | -| `frontend-sba/.env` | Active frontend config (gitignored) | -| `frontend-sba/.env.dev` | Local development settings | -| `frontend-sba/.env.prod` | Production settings | - -### 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 (JSON array) -- `ALLOWED_DISCORD_IDS` - User whitelist (comma-separated, empty = all) - -**Frontend** (in `frontend-*/.env`): -- `NUXT_PUBLIC_API_URL` - Backend API URL (public, client-side) -- `NUXT_API_URL_INTERNAL` - Backend URL for SSR (Docker internal: `http://backend:8000`) -- `NUXT_PUBLIC_WS_URL` - WebSocket URL -- `NUXT_PUBLIC_DISCORD_CLIENT_ID` - OAuth client ID (public) -- `NUXT_PUBLIC_DISCORD_REDIRECT_URI` - OAuth callback URL - -### Discord OAuth Setup - -Both environments require redirect URIs in [Discord Developer Portal](https://discord.com/developers/applications): - -| Environment | Redirect URI | -|-------------|--------------| -| dev | `http://localhost:8000/api/auth/discord/callback/server` | -| prod | `https://gameplay-demo.manticorum.com/api/auth/discord/callback/server` | - -### Manual Environment Switching - -If you need to switch between dev/prod configs without Docker: - -```bash -./scripts/env-switch.sh dev # Copy .env.dev → .env -./scripts/env-switch.sh prod # Copy .env.prod → .env -``` - -The `start.sh` script handles this automatically based on mode. - -## Development Guidelines - -### Code Quality -- **Python**: Dataclasses preferred, rotating loggers with `f'{__name__}.'` -- **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 +- **SBA**: Minimal player data (id, name, image), simpler rules +- **PD**: Detailed scouting data, complex probability calculations -### PD League -- Detailed scouting data on players -- Complex probability calculations -- Additional analytics requirements +## References -## 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 20 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) -- ✅ Uncapped hit interactive decision tree (SINGLE_UNCAPPED, DOUBLE_UNCAPPED) -- ✅ 2481/2481 tests passing (100%) - -**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. +- **Full PRD**: `prd-web-scorecard-1.1.md` +- **Native dev setup**: `NATIVE_DEV_SETUP.md` +- Subdirectories have their own CLAUDE.md files for implementation details