# rli8145/alphahex architecture

> Architecture diagram of the GitHub repository rli8145/alphahex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rli8145/alphahex
- Repository: https://github.com/rli8145/alphahex

## Overview

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: [`packages/catan_api/routes_games.py`](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_games.py) (Game routes), [`packages/catan_bots/mcts_bot.py`](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/mcts_bot.py) (MCTS bot), [`packages/catan_api/app.py`](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/app.py) (FastAPI app), [`packages/catan_bots/train_mcts_nn.py`](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/train_mcts_nn.py) (Neural self-play trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Game interface<br/>[App.jsx]"]
  node_webparts["Game panels"]
  node_webapi["API client<br/>[api.js]"]
  node_authpanel["Account panel<br/>[AuthPanel.jsx]"]
  node_supabaseclient["Supabase client<br/>[supabase.js]"]
end

subgraph group_api["API and accounts"]
  node_backend["FastAPI app<br/>[app.py]"]
  node_gameroutes["Game routes<br/>[routes_games.py]"]
  node_botroutes["Bot routes<br/>[routes_bots.py]"]
  node_replayroutes["Replay routes<br/>[routes_replays.py]"]
  node_auth["Auth verification<br/>[auth.py]"]
  node_dbaccess["Game history access<br/>[db.py]"]
end

subgraph group_engine["Catan engine"]
  node_gamestate["Game state<br/>[state.py]"]
  node_rules["Rules and actions<br/>[rules.py]"]
  node_observation["Player observation<br/>[observation.py]"]
  node_replay["Replay storage<br/>[replay.py]"]
  node_simulator["Game simulator<br/>[simulator.py]"]
end

subgraph group_agent["Bot agent"]
  node_mcts["MCTS bot<br/>[mcts_bot.py]"]
  node_value["Value-policy network<br/>[value_network.py]"]
end

subgraph group_training["Agent training"]
  node_trainer["Neural self-play trainer<br/>[train_mcts_nn.py]"]
  node_heuristictrainer["Heuristic trainer<br/>[train_mcts.py]"]
end

node_player(("Player"))
node_postgres[("Postgres")]
node_supabaseauth["Supabase Auth"]

node_player -->|"plays"| node_webapp
node_webapp -->|"renders"| node_webparts
node_webapp -->|"requests games"| node_webapi
node_webapi -->|"calls game API"| node_gameroutes
node_backend -->|"dispatches"| node_gameroutes
node_backend -->|"dispatches"| node_botroutes
node_backend -->|"dispatches"| node_replayroutes
node_gameroutes -->|"initializes and restores"| node_gamestate
node_gameroutes -->|"applies actions"| node_rules
node_gameroutes -->|"gets legal actions"| node_rules
node_gameroutes -->|"builds observations"| node_observation
node_gameroutes -->|"requests bot action"| node_mcts
node_gameroutes -->|"runs bot matches"| node_simulator
node_gameroutes -->|"records finished games"| node_dbaccess
node_dbaccess -.->|"reads and writes"| node_postgres
node_gameroutes -->|"depends on user"| node_auth
node_authpanel -->|"loads history"| node_webapi
node_authpanel -->|"signs in and out"| node_supabaseclient
node_auth -.->|"verifies tokens"| node_supabaseauth
node_replayroutes -->|"lists and loads"| node_replay
node_mcts -->|"searches legal moves"| node_rules
node_mcts -->|"evaluates positions"| node_value
node_trainer -->|"collects self-play"| node_simulator
node_trainer -->|"generates moves"| node_mcts
node_trainer -->|"trains checkpoints"| node_value
node_heuristictrainer -->|"evaluates candidates"| node_simulator
node_heuristictrainer -->|"optimizes weights"| node_mcts
node_value -.->|"serves evaluations"| node_mcts

click node_webapp "https://github.com/rli8145/alphahex/blob/main/web/src/App.jsx"
click node_webparts "https://github.com/rli8145/alphahex/tree/main/web/src/components"
click node_webapi "https://github.com/rli8145/alphahex/blob/main/web/src/api.js"
click node_authpanel "https://github.com/rli8145/alphahex/blob/main/web/src/components/AuthPanel.jsx"
click node_supabaseclient "https://github.com/rli8145/alphahex/blob/main/web/src/supabase.js"
click node_backend "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/app.py"
click node_gameroutes "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_games.py"
click node_botroutes "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_bots.py"
click node_replayroutes "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_replays.py"
click node_auth "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/auth.py"
click node_dbaccess "https://github.com/rli8145/alphahex/blob/main/packages/catan_api/db.py"
click node_gamestate "https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/state.py"
click node_rules "https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/rules.py"
click node_observation "https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/observation.py"
click node_replay "https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/replay.py"
click node_mcts "https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/mcts_bot.py"
click node_value "https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/value_network.py"
click node_simulator "https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/simulator.py"
click node_trainer "https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/train_mcts_nn.py"
click node_heuristictrainer "https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/train_mcts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_webparts,node_webapi,node_authpanel,node_supabaseclient toneBlue
class node_backend,node_gameroutes,node_botroutes,node_replayroutes,node_auth,node_dbaccess,node_postgres toneAmber
class node_gamestate,node_rules,node_observation,node_replay,node_simulator toneMint
class node_mcts,node_value toneRose
class node_trainer,node_heuristictrainer,node_player,node_supabaseauth toneIndigo
```

## Components

### Web client

- [Game interface](https://github.com/rli8145/alphahex/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Game panels](https://github.com/rli8145/alphahex/tree/main/web/src/components): `web/src/components`
- [API client](https://github.com/rli8145/alphahex/blob/main/web/src/api.js): `web/src/api.js`
- [Account panel](https://github.com/rli8145/alphahex/blob/main/web/src/components/AuthPanel.jsx): `web/src/components/AuthPanel.jsx`
- [Supabase client](https://github.com/rli8145/alphahex/blob/main/web/src/supabase.js): `web/src/supabase.js`

### API and accounts

- [FastAPI app](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/app.py): `packages/catan_api/app.py`
- [Game routes](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_games.py): `packages/catan_api/routes_games.py`
- [Bot routes](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_bots.py): `packages/catan_api/routes_bots.py`
- [Replay routes](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/routes_replays.py): `packages/catan_api/routes_replays.py`
- [Auth verification](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/auth.py): `packages/catan_api/auth.py`
- [Game history access](https://github.com/rli8145/alphahex/blob/main/packages/catan_api/db.py): `packages/catan_api/db.py`

### Catan engine

- [Game state](https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/state.py): `packages/catan_engine/state.py`
- [Rules and actions](https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/rules.py): `packages/catan_engine/rules.py`
- [Player observation](https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/observation.py): `packages/catan_engine/observation.py`
- [Replay storage](https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/replay.py): `packages/catan_engine/replay.py`
- [Game simulator](https://github.com/rli8145/alphahex/blob/main/packages/catan_engine/simulator.py): `packages/catan_engine/simulator.py`

### Bot agent

- [MCTS bot](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/mcts_bot.py): `packages/catan_bots/mcts_bot.py`
- [Value-policy network](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/value_network.py): `packages/catan_bots/value_network.py`

### Agent training

- [Neural self-play trainer](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/train_mcts_nn.py): `packages/catan_bots/train_mcts_nn.py`
- [Heuristic trainer](https://github.com/rli8145/alphahex/blob/main/packages/catan_bots/train_mcts.py): `packages/catan_bots/train_mcts.py`

### Other components

- **Player**
- **Postgres**
- **Supabase Auth**

## Connections

- 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