How rli8145/alphahex works
AlphaHex is a browser-playable 1v1 Catan game against an MCTS bot, backed by a FastAPI service and rules engine. The main flow is a player’s browser action through the API to legal-action validation and state advancement, with bot turns selected by MCTS; updated state and legal actions return to the client. The product also exposes bot/replay and game-history features, optional sign-in, and documented self-play training. Training and some subsystem wiring are represented from README documentation because their implementation was not fully sampled.
Main entry points: routes_games.py Game routes · mcts_bot.py MCTS bot · app.py FastAPI app · train_mcts_nn.py Neural self-play trainer
Components 23
Web client
- Game interface
web/src/App.jsx - Game panels
web/src/components - API client
web/src/api.js - Account panel
web/src/components/AuthPanel.jsx - Supabase client
web/src/supabase.js
API and accounts
- FastAPI app
packages/catan_api/app.py - Game routes
packages/catan_api/routes_games.py - Bot routes
packages/catan_api/routes_bots.py - Replay routes
packages/catan_api/routes_replays.py - Auth verification
packages/catan_api/auth.py - Game history access
packages/catan_api/db.py
Catan engine
- Game state
packages/catan_engine/state.py - Rules and actions
packages/catan_engine/rules.py - Player observation
packages/catan_engine/observation.py - Replay storage
packages/catan_engine/replay.py - Game simulator
packages/catan_engine/simulator.py
Bot agent
- MCTS bot
packages/catan_bots/mcts_bot.py - Value-policy network
packages/catan_bots/value_network.py
Agent training
- Neural self-play trainer
packages/catan_bots/train_mcts_nn.py - Heuristic trainer
packages/catan_bots/train_mcts.py
Other components
- Player
- Postgres
- Supabase Auth
Connections 28
- Player → Game interface: plays
- Game interface → Game panels: renders
- Game interface → API client: requests games
- API client → Game routes: calls game API
- FastAPI app → Game routes: dispatches
- FastAPI app → Bot routes: dispatches
- FastAPI app → Replay routes: dispatches
- Game routes → Game state: initializes and restores
- Game routes → Rules and actions: applies actions
- Game routes → Rules and actions: gets legal actions
- Game routes → Player observation: builds observations
- Game routes → MCTS bot: requests bot action
- Game routes → Game simulator: runs bot matches
- Game routes → Game history access: records finished games
- Game history access → Postgres: reads and writes
- Game routes → Auth verification: depends on user
- Account panel → API client: loads history
- Account panel → Supabase client: signs in and out
- Auth verification → Supabase Auth: verifies tokens
- Replay routes → Replay storage: lists and loads
- MCTS bot → Rules and actions: searches legal moves
- MCTS bot → Value-policy network: evaluates positions
- Neural self-play trainer → Game simulator: collects self-play
- Neural self-play trainer → MCTS bot: generates moves
- Neural self-play trainer → Value-policy network: trains checkpoints
- Heuristic trainer → Game simulator: evaluates candidates
- Heuristic trainer → MCTS bot: optimizes weights
- Value-policy network → MCTS bot: serves evaluations