# phuc11731510/chess_variant_engine architecture

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

- Interactive diagram: https://gitdiagram.com/phuc11731510/chess_variant_engine
- Repository: https://github.com/phuc11731510/chess_variant_engine

## Overview

This repository contains a custom Fairy-Stockfish/LCZero chess-variant engine plus a Python self-play training pipeline. The primary play path accepts UCI commands or terminal play, configures a neural backend, searches positions with MCTS, and returns a selected move; separate documented command modes support self-play, arena matches, and diagnostics. The tree and sampled source support these principal entry points and search/backend flow, but README content is absent and several mode implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`custom_engine/src/main.cc`](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/main.cc) (Engine modes), [`custom_engine/src/app/uci_nn_engine.cc`](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/uci_nn_engine.cc) (UCI NN engine), [`custom_engine/src/app/backend_factory.cc`](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/backend_factory.cc) (Backend factory), [`custom_engine/src/search/classic/search.cc`](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/search/classic/search.cc) (MCTS search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Engine play"]
  node_entry["Engine modes<br/>[main.cc]"]
  node_uci["UCI NN engine<br/>[uci_nn_engine.cc]"]
  node_terminal["Terminal play<br/>[play_mode.cc]"]
  node_arena["Model arena<br/>[arena_mode.cc]"]
  node_ffi["Python FFI<br/>[fairyzero_ffi.h]"]
  node_benchmark["NN benchmark<br/>[bench_nn.cc]"]
  node_audit["Generation audit"]
end

subgraph group_neural["Neural search"]
  node_backend_factory["Backend factory<br/>[backend_factory.cc]"]
  node_onnx["ONNX backend<br/>[onnx_backend.cc]"]
  node_batching["Batching backend"]
  node_cache[("Evaluation cache<br/>[zero_heap_cache.cc]")]
  node_classic_search["MCTS search<br/>[search.cc]"]
  node_tree["Search tree<br/>[node.cc]"]
  node_encoder["Position encoder<br/>[encoder.cc]"]
end

subgraph group_training["Training lifecycle"]
  node_selfplay["Self-play mode<br/>[selfplay_mode.cc]"]
  node_generation["Seed generation<br/>[make_seed.py]"]
  node_training_data["Training records<br/>[writer.cc]"]
  node_dataset["Dataset loader<br/>[dataset.py]"]
  node_trainer["Model training<br/>[train.py]"]
  node_model["ONNX model"]
end

subgraph group_variant["Variant rules"]
  node_board["Variant board<br/>[board.cc]"]
  node_variant_rules["Variant rules<br/>[variant.cpp]"]
  node_variant_parser["Variant parser<br/>[parser.cpp]"]
end

node_user(("GUI or player"))

node_user -->|"starts mode"| node_entry
node_entry -->|"dispatches UCI"| node_uci
node_entry -->|"dispatches play"| node_terminal
node_entry -->|"dispatches arena"| node_arena
node_entry -->|"dispatches self-play"| node_selfplay
node_uci -->|"builds backend"| node_backend_factory
node_terminal -->|"builds backend"| node_backend_factory
node_selfplay -->|"builds backend"| node_backend_factory
node_backend_factory -->|"creates backend"| node_onnx
node_onnx -->|"uses batching"| node_batching
node_batching -->|"checks cache"| node_cache
node_uci -->|"starts search"| node_classic_search
node_terminal -->|"starts search"| node_classic_search
node_classic_search -->|"updates nodes"| node_tree
node_classic_search -->|"requests evaluations"| node_batching
node_uci -->|"parses positions"| node_board
node_board -->|"applies rules"| node_variant_rules
node_variant_parser -->|"configures rules"| node_variant_rules
node_selfplay -->|"writes records"| node_training_data
node_generation -.->|"creates seed data"| node_training_data
node_training_data -->|"loads records"| node_dataset
node_dataset -->|"supplies examples"| node_trainer
node_trainer -->|"exports ONNX"| node_model
node_model -->|"loads weights"| node_backend_factory
node_user -.->|"sends commands"| node_ffi
node_ffi -.->|"drives engine"| node_uci
node_entry -->|"dispatches benchmark"| node_benchmark
node_entry -->|"dispatches audit"| node_audit

click node_entry "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/main.cc"
click node_uci "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/uci_nn_engine.cc"
click node_terminal "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/play_mode.cc"
click node_arena "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/arena_mode.cc"
click node_selfplay "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/selfplay_mode.cc"
click node_generation "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/make_seed.py"
click node_training_data "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/trainingdata/writer.cc"
click node_dataset "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/dataset.py"
click node_trainer "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/train.py"
click node_backend_factory "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/backend_factory.cc"
click node_onnx "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/onnx_backend.cc"
click node_batching "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/batching_backend.cc"
click node_cache "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/zero_heap_cache.cc"
click node_classic_search "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/search/classic/search.cc"
click node_tree "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/search/classic/node.cc"
click node_encoder "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/chess/encoder.cc"
click node_board "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/chess/board.cc"
click node_variant_rules "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/chess/variant.cpp"
click node_variant_parser "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/chess/parser.cpp"
click node_ffi "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/fairyzero_ffi.h"
click node_benchmark "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/bench_nn.cc"
click node_audit "https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/audit_generation.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_entry,node_uci,node_terminal,node_arena,node_ffi,node_benchmark,node_audit,node_user toneBlue
class node_backend_factory,node_onnx,node_batching,node_cache,node_classic_search,node_tree,node_encoder toneAmber
class node_selfplay,node_generation,node_training_data,node_dataset,node_trainer,node_model toneMint
class node_board,node_variant_rules,node_variant_parser toneRose
```

## Components

### Engine play

- [Engine modes](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/main.cc): `custom_engine/src/main.cc`
- [UCI NN engine](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/uci_nn_engine.cc): `custom_engine/src/app/uci_nn_engine.cc`
- [Terminal play](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/play_mode.cc): `custom_engine/src/app/play_mode.cc`
- [Model arena](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/arena_mode.cc): `custom_engine/src/app/arena_mode.cc`
- [Python FFI](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/fairyzero_ffi.h): `custom_engine/src/app/fairyzero_ffi.h`
- [NN benchmark](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/bench_nn.cc): `custom_engine/src/app/bench_nn.cc`
- [Generation audit](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/audit_generation.py): `custom_engine/python/audit_generation.py`

### Neural search

- [Backend factory](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/backend_factory.cc): `custom_engine/src/app/backend_factory.cc`
- [ONNX backend](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/onnx_backend.cc): `custom_engine/src/lczero_chess/neural/onnx_backend.cc`
- [Batching backend](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/batching_backend.cc): `custom_engine/src/lczero_chess/neural/batching_backend.cc`
- [Evaluation cache](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/neural/zero_heap_cache.cc): `custom_engine/src/lczero_chess/neural/zero_heap_cache.cc`
- [MCTS search](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/search/classic/search.cc): `custom_engine/src/search/classic/search.cc`
- [Search tree](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/search/classic/node.cc): `custom_engine/src/search/classic/node.cc`
- [Position encoder](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/chess/encoder.cc): `custom_engine/src/lczero_chess/chess/encoder.cc`

### Training lifecycle

- [Self-play mode](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/app/selfplay_mode.cc): `custom_engine/src/app/selfplay_mode.cc`
- [Seed generation](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/make_seed.py): `custom_engine/python/make_seed.py`
- [Training records](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/trainingdata/writer.cc): `custom_engine/src/lczero_chess/trainingdata/writer.cc`
- [Dataset loader](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/dataset.py): `custom_engine/python/dataset.py`
- [Model training](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/python/train.py): `custom_engine/python/train.py`
- **ONNX model**

### Variant rules

- [Variant board](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/lczero_chess/chess/board.cc): `custom_engine/src/lczero_chess/chess/board.cc`
- [Variant rules](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/chess/variant.cpp): `custom_engine/src/chess/variant.cpp`
- [Variant parser](https://github.com/phuc11731510/chess_variant_engine/blob/main/custom_engine/src/chess/parser.cpp): `custom_engine/src/chess/parser.cpp`

### Other components

- **GUI or player**

## Connections

- GUI or player → Engine modes: starts mode
- Engine modes → UCI NN engine: dispatches UCI
- Engine modes → Terminal play: dispatches play
- Engine modes → Model arena: dispatches arena
- Engine modes → Self-play mode: dispatches self-play
- UCI NN engine → Backend factory: builds backend
- Terminal play → Backend factory: builds backend
- Self-play mode → Backend factory: builds backend
- Backend factory → ONNX backend: creates backend
- ONNX backend → Batching backend: uses batching
- Batching backend → Evaluation cache: checks cache
- UCI NN engine → MCTS search: starts search
- Terminal play → MCTS search: starts search
- MCTS search → Search tree: updates nodes
- MCTS search → Batching backend: requests evaluations
- UCI NN engine → Variant board: parses positions
- Variant board → Variant rules: applies rules
- Variant parser → Variant rules: configures rules
- Self-play mode → Training records: writes records
- Seed generation → Training records: creates seed data
- Training records → Dataset loader: loads records
- Dataset loader → Model training: supplies examples
- Model training → ONNX model: exports ONNX
- ONNX model → Backend factory: loads weights
- GUI or player → Python FFI: sends commands
- Python FFI → UCI NN engine: drives engine
- Engine modes → NN benchmark: dispatches benchmark
- Engine modes → Generation audit: dispatches audit