todo.md

ChessEcon v2 — Monorepo TODO

Phase 1: Scaffold

• Create monorepo directory structure
• Write shared/models.py (Pydantic data models shared across backend + training)
• Write .env.example with all keys documented

Phase 2: Backend (Python FastAPI)

• backend/main.py — FastAPI app entry point, mounts static frontend
• backend/chess/engine.py — python-chess game logic
• backend/api/game_router.py — game management REST API
• backend/economy/ledger.py — wallets, tournament organizer, transactions
• backend/agents/complexity.py — position complexity analyzer
• backend/agents/claude_coach.py — Anthropic API integration (minimal usage)
• backend/api/websocket.py — WebSocket event bus (game events, training metrics)
• backend/api/training_router.py — training status REST API
• backend/requirements.txt

Phase 3: Training (Standalone Python)

• training/config.py — training configuration from .env
• training/self_play.py — self-play game loop, episode collection
• training/trainers/grpo.py — GRPO trainer
• training/trainers/ppo.py — PPO trainer
• training/trainers/rloo.py — RLOO trainer
• training/trainers/base.py — abstract base trainer
• training/model_loader.py — HuggingFace model download + load
• training/reward.py — combined chess + economic reward function
• training/run.py — training entry point CLI
• training/requirements.txt

Phase 4: Frontend (React TypeScript)

• frontend/package.json + vite.config.ts
• frontend/src/lib/useBackendWS.ts — WebSocket client hook (real backend mode)
• frontend/src/lib/simulation.ts — browser simulation (offline mode)
• frontend/src/components/ChessBoard.tsx — live chess board
• frontend/src/components/TrainingCharts.tsx — GRPO metrics charts
• frontend/src/components/WalletChart.tsx — wallet history chart
• frontend/src/components/EconomicPerformance.tsx — P&L chart (full-width bottom row)
• frontend/src/components/EventFeed.tsx — live event log
• frontend/src/components/Panel.tsx — shared panel wrapper
• frontend/src/pages/Home.tsx — main dashboard with simulation + backend modes

Phase 5: Docker

• Dockerfile — multi-stage: frontend build → backend serve
• docker-compose.yml — app + trainer services
• docker-compose.gpu.yml — GPU override for trainer
• .env.example — all keys documented (ANTHROPIC_API_KEY, HF_TOKEN, PLAYER_MODEL, RL_METHOD)
• Makefile — common commands
• .dockerignore
• docker-entrypoint.sh — model download on startup

Phase 6: Validation

• All 5 unit tests pass (ChessEngine, Economy, Complexity, Models, TrainingConfig)
• README.md written with full setup instructions
• Project packaged as zip