7d28eebd24
- Create frontend-sba/.env.example and frontend-pd/.env.example templates - Fix hardcoded allowedHosts in nuxt.config.ts (now reads NUXT_ALLOWED_HOSTS) - Add NUXT_ALLOWED_HOSTS support to frontend-pd/nuxt.config.ts - Update docker-compose.yml with missing env vars: - FRONTEND_URL, DISCORD_SERVER_REDIRECT_URI - ALLOWED_DISCORD_IDS, WS_HEARTBEAT_INTERVAL, WS_CONNECTION_TIMEOUT - NUXT_ALLOWED_HOSTS for both frontends - Create docker-compose.prod.yml for production overrides - Update root .env.example with new variables - Add "Multi-Domain Deployment" section to README.md with checklist - Update all CLAUDE.md files with environment configuration docs - Remove obsolete 'version' attribute from docker-compose files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
216 lines
7.1 KiB
Markdown
216 lines
7.1 KiB
Markdown
# 🚨 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
|
|
```bash
|
|
# 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.
|