# rivorx/play_with_ai_games architecture

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

- Interactive diagram: https://gitdiagram.com/rivorx/play_with_ai_games
- Repository: https://github.com/rivorx/play_with_ai_games

## Overview

Play With AI Games is a collection of three game-agent projects. The chess workflow trains a CNN first from master games, then through MCTS self-play; models are evaluated by Elo and can be played through a GUI or UCI adapter. Snake and Solitaire provide separate RL-agent training and demonstration workflows. The graph preserves documented capabilities even where their implementations were not sampled; dashed, uncited links mark relationships that the available excerpts do not establish. Chess module relationships are limited to source-index references and the provided excerpts.

Main entry points: [`chess/src/game/backend.py`](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/game/backend.py) (Board rules), [`chess/src/ui/uci_engine.py`](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/ui/uci_engine.py) (UCI adapter), [`chess/src/inference/central.py`](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/inference/central.py) (Batched inference), [`chess/src/mcts/search.py`](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/mcts/search.py) (Gumbel MCTS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chess_play["Chess play and inference"]
  node_chess_gui["Chess GUI<br/>[game_setup.py]"]
  node_uci_adapter["UCI adapter<br/>[uci_engine.py]"]
  node_game_rules["Board rules<br/>[backend.py]"]
  node_search["Gumbel MCTS<br/>[search.py]"]
  node_model_api["Model loading<br/>[model.py]"]
  node_network["SE-CNN v9<br/>[se_cnn_v9.py]"]
  node_inference["Batched inference<br/>[central.py]"]
  node_inference_transport["Inference transport<br/>[shared_memory.py]"]
end

subgraph group_chess_learning["Chess training and evaluation"]
  node_il_data["Master-game data<br/>[preprocessing.py]"]
  node_il_dataset["Training dataset<br/>[dataset.py]"]
  node_il_trainer["Imitation training<br/>[trainer.py]"]
  node_selfplay["Self-play engine<br/>[engine.py]"]
  node_selfplay_workers["Self-play workers<br/>[workers.py]"]
  node_replay[("RL replay<br/>[replay.py]")]
  node_rl_trainer["Reinforcement training<br/>[trainer.py]"]
  node_elo["Elo evaluation<br/>[elo_estimator.py]"]
end

subgraph group_snake["Snake agent"]
  node_snake_train["PPO training<br/>[train.py]"]
  node_snake_model["Snake CNN<br/>[model.py]"]
  node_snake_analysis["Model analysis<br/>[analyze_model.py]"]
  node_snake_gif["GIF generation<br/>[make_gif.py]"]
end

subgraph group_solitaire["Solitaire agent"]
  node_solitaire_train["MaskablePPO training<br/>[train.py]"]
  node_solitaire_model["Solitaire model<br/>[model.py]"]
  node_solitaire_cnn["CNN component<br/>[cnn.py]"]
  node_solitaire_gif["GIF generation<br/>[make_gif.py]"]
end

node_chess_user(("Player or operator"))
node_uci_client(("UCI client"))
node_stockfish["Stockfish"]
node_snake_user(("Snake player or operator"))
node_solitaire_user(("Solitaire player or operator"))

node_chess_user -->|"plays through"| node_chess_gui
node_chess_gui -.->|"uses rules"| node_game_rules
node_uci_client -->|"sends commands"| node_uci_adapter
node_uci_adapter -->|"uses boards"| node_game_rules
node_uci_adapter -->|"loads model"| node_model_api
node_uci_adapter -->|"runs search"| node_search
node_search -->|"queries positions"| node_game_rules
node_model_api -->|"creates model"| node_network
node_inference -->|"runs inference"| node_network
node_inference -->|"serves requests"| node_search
node_inference -->|"transfers batches"| node_inference_transport
node_il_data -->|"decodes positions"| node_game_rules
node_il_dataset -->|"uses board data"| node_game_rules
node_il_trainer -.->|"loads datasets"| node_il_dataset
node_selfplay_workers -->|"runs games"| node_selfplay
node_selfplay -->|"searches moves"| node_search
node_selfplay -->|"plays positions"| node_game_rules
node_selfplay_workers -->|"requests inference"| node_inference
node_rl_trainer -.->|"uses replay"| node_replay
node_rl_trainer -.->|"starts self-play"| node_selfplay_workers
node_elo -->|"plays matches"| node_stockfish
node_chess_user -.->|"connects engine"| node_uci_client
node_snake_user -->|"trains agent"| node_snake_train
node_snake_train -.->|"uses network"| node_snake_model
node_snake_user -->|"analyzes model"| node_snake_analysis
node_snake_user -->|"generates demo"| node_snake_gif
node_solitaire_user -->|"trains agent"| node_solitaire_train
node_solitaire_train -.->|"uses model"| node_solitaire_model
node_solitaire_model -.->|"uses CNN"| node_solitaire_cnn
node_solitaire_user -->|"records demo"| node_solitaire_gif

click node_chess_gui "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/ui/game_setup.py"
click node_uci_adapter "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/ui/uci_engine.py"
click node_game_rules "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/game/backend.py"
click node_search "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/mcts/search.py"
click node_model_api "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/model.py"
click node_network "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/architecture/se_cnn_v9.py"
click node_inference "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/inference/central.py"
click node_inference_transport "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/inference/shared_memory.py"
click node_il_data "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/data/se_cnn_v9/preprocessing.py"
click node_il_dataset "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/data/se_cnn_v9/dataset.py"
click node_il_trainer "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/il/trainer.py"
click node_selfplay "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/selfplay/engine.py"
click node_selfplay_workers "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/selfplay/workers.py"
click node_replay "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/rl/replay.py"
click node_rl_trainer "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/rl/trainer.py"
click node_elo "https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/evaluation/elo_estimator.py"
click node_snake_train "https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/train.py"
click node_snake_model "https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/model.py"
click node_snake_analysis "https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/debug/analyze_model.py"
click node_snake_gif "https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/debug/make_gif.py"
click node_solitaire_train "https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/train.py"
click node_solitaire_model "https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/model.py"
click node_solitaire_cnn "https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/cnn.py"
click node_solitaire_gif "https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/debug/make_gif.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_chess_gui,node_uci_adapter,node_game_rules,node_search,node_model_api,node_network,node_inference,node_inference_transport,node_uci_client toneBlue
class node_il_data,node_il_dataset,node_il_trainer,node_selfplay,node_selfplay_workers,node_replay,node_rl_trainer,node_elo toneAmber
class node_snake_train,node_snake_model,node_snake_analysis,node_snake_gif toneMint
class node_solitaire_train,node_solitaire_model,node_solitaire_cnn,node_solitaire_gif toneRose
class node_chess_user,node_stockfish,node_snake_user,node_solitaire_user toneIndigo
```

## Components

### Chess play and inference

- [Chess GUI](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/ui/game_setup.py): `chess/src/ui/game_setup.py`
- [UCI adapter](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/ui/uci_engine.py): `chess/src/ui/uci_engine.py`
- [Board rules](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/game/backend.py): `chess/src/game/backend.py`
- [Gumbel MCTS](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/mcts/search.py): `chess/src/mcts/search.py`
- [Model loading](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/model.py): `chess/src/model.py`
- [SE-CNN v9](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/architecture/se_cnn_v9.py): `chess/src/models/architecture/se_cnn_v9.py`
- [Batched inference](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/inference/central.py): `chess/src/inference/central.py`
- [Inference transport](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/inference/shared_memory.py): `chess/src/inference/shared_memory.py`

### Chess training and evaluation

- [Master-game data](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/data/se_cnn_v9/preprocessing.py): `chess/src/models/data/se_cnn_v9/preprocessing.py`
- [Training dataset](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/models/data/se_cnn_v9/dataset.py): `chess/src/models/data/se_cnn_v9/dataset.py`
- [Imitation training](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/il/trainer.py): `chess/src/training/il/trainer.py`
- [Self-play engine](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/selfplay/engine.py): `chess/src/selfplay/engine.py`
- [Self-play workers](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/selfplay/workers.py): `chess/src/selfplay/workers.py`
- [RL replay](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/rl/replay.py): `chess/src/training/rl/replay.py`
- [Reinforcement training](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/training/rl/trainer.py): `chess/src/training/rl/trainer.py`
- [Elo evaluation](https://github.com/rivorx/play_with_ai_games/blob/main/chess/src/evaluation/elo_estimator.py): `chess/src/evaluation/elo_estimator.py`

### Snake agent

- [PPO training](https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/train.py): `snake/scripts/train.py`
- [Snake CNN](https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/model.py): `snake/scripts/model.py`
- [Model analysis](https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/debug/analyze_model.py): `snake/scripts/debug/analyze_model.py`
- [GIF generation](https://github.com/rivorx/play_with_ai_games/blob/main/snake/scripts/debug/make_gif.py): `snake/scripts/debug/make_gif.py`

### Solitaire agent

- [MaskablePPO training](https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/train.py): `solitaire/scripts/train.py`
- [Solitaire model](https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/model.py): `solitaire/scripts/model.py`
- [CNN component](https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/cnn.py): `solitaire/scripts/cnn.py`
- [GIF generation](https://github.com/rivorx/play_with_ai_games/blob/main/solitaire/scripts/debug/make_gif.py): `solitaire/scripts/debug/make_gif.py`

### Other components

- **Player or operator**
- **UCI client**
- **Stockfish**
- **Snake player or operator**
- **Solitaire player or operator**

## Connections

- Player or operator → Chess GUI: plays through
- Chess GUI → Board rules: uses rules
- UCI client → UCI adapter: sends commands (evidence: `chess/src/ui/uci_engine.py`)
- UCI adapter → Board rules: uses boards (evidence: `chess/src/ui/uci_engine.py`)
- UCI adapter → Model loading: loads model (evidence: `chess/src/ui/uci_engine.py`)
- UCI adapter → Gumbel MCTS: runs search (evidence: `chess/src/ui/uci_engine.py`)
- Gumbel MCTS → Board rules: queries positions (evidence: `chess/src/mcts/search.py`)
- Model loading → SE-CNN v9: creates model (evidence: `chess/src/model.py`)
- Batched inference → SE-CNN v9: runs inference (evidence: `chess/src/inference/central.py`)
- Batched inference → Gumbel MCTS: serves requests (evidence: `chess/src/inference/central.py`)
- Batched inference → Inference transport: transfers batches (evidence: `chess/src/inference/central.py`)
- Master-game data → Board rules: decodes positions
- Training dataset → Board rules: uses board data (evidence: `chess/src/models/data/se_cnn_v9/dataset.py`)
- Imitation training → Training dataset: loads datasets
- Self-play workers → Self-play engine: runs games (evidence: `chess/src/selfplay/workers.py`)
- Self-play engine → Gumbel MCTS: searches moves (evidence: `chess/src/selfplay/engine.py`)
- Self-play engine → Board rules: plays positions (evidence: `chess/src/selfplay/engine.py`)
- Self-play workers → Batched inference: requests inference (evidence: `chess/src/selfplay/workers.py`)
- Reinforcement training → RL replay: uses replay
- Reinforcement training → Self-play workers: starts self-play
- Elo evaluation → Stockfish: plays matches
- Player or operator → UCI client: connects engine
- Snake player or operator → PPO training: trains agent
- PPO training → Snake CNN: uses network
- Snake player or operator → Model analysis: analyzes model
- Snake player or operator → GIF generation: generates demo
- Solitaire player or operator → MaskablePPO training: trains agent
- MaskablePPO training → Solitaire model: uses model
- Solitaire model → CNN component: uses CNN
- Solitaire player or operator → GIF generation: records demo