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 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
187bd1ccae
commit
880adb315e
318
CLAUDE.md
318
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__}.<className>'`
|
||||
- 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__}.<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
|
||||
- **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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user