# rn5f107s2/molybdenum architecture

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

- Interactive diagram: https://gitdiagram.com/rn5f107s2/molybdenum
- Repository: https://github.com/rn5f107s2/molybdenum

## Overview

1. **What this repository is**
   - Molybdenum is a standalone **C++ chess engine**.
   - Its runtime architecture is centered on a single executable that speaks **UCI (Universal Chess Interface)** so it can be driven by a GUI like cutechess or by direct CLI commands.

2. **Top-level execution flow**
   - `main.cpp` is the entry point.
   - It initializes engine state, then hands control to the **UCI command loop**.
   - From there, the engine alternates between:
     - receiving position/setup commands,
     - starting a search on demand,
     - and emitting UCI-style `info`/`bestmove` output.

3. **Protocol and command handling boundary**
   - `UCI.cpp`, `UCI.h`, `UCIOptions.cpp`, and `UCIOptions.h` form the **front door** of the engine.
   - This layer parses incoming text commands such as `position`, `go`, `bench`, `eval`, and `d`.
   - It is the boundary between external clients and internal chess logic.

4. **Board state and move representation**
   - `Position.cpp/.h`, `Move.h`, `BitStuff.h`, and `Constants.h` define the engine’s **core chess state** and low-level move/board abstractions.
   - This is the central data model that everything else reads from and writes to: search, evaluation, move generation, and perft.

5. **Move generation subsystem**
   - `Movegen.h`, `MagicBitboards.h`, and `Move.h` implement legal/pseudo-legal move generation.
   - The presence of **magic bitboards** indicates a bitboard-based move generator optimized for sliding pieces.
   - This subsystem supplies candidate moves to the searcher and is also likely used by perft and test/bench paths.

6. **Search subsystem**
   - `search.cpp/.h`, `searchUtil.h`, `Movepicker.h`, `Transpositiontable.cpp/.h`, and `timemanagement.h`/`timemanagment.cpp` make up the engine’s **thinking core**.
   - Search consumes a `Position`, generates and orders moves, consults the transposition table, and applies pruning/selection heuristics.
   - It is responsible for producing principal variation, scores, node counts, and the final best move.

7. **Evaluation subsystem**
   - `eval.h`, `PSQT.h`, `nnue.cpp/.h`, `simd.h`, and `src/incbin/` are the engine’s **evaluation layer**.
   - README states the engine uses an **NNUE-style neural network** with architecture `(768->32)x2->1`.
   - `PSQT` suggests some positional scoring support alongside the NNUE path, while `simd.h` likely provides vectorized acceleration for evaluation and/or move processing.

8. **Performance infrastructure**
   - `Transpositiontable.*` is a major cache used by search to avoid re-evaluating positions.
   - `thread.cpp/.h` indicates the engine supports **multi-threaded search**, with shared search state and per-thread coordination.
   - `bench.h` and `Perft.h` support diagnostics and performance validation rather than playing strength directly.

9. **Time management**
   - `timemanagement.h` and `timemanagment.cpp` control how long the engine searches before stopping.
   - This layer converts UCI limits like `movetime`, `depth`, `nodes`, or `infinite` into search-stop conditions.

10. **Auxiliary tools and training support**
   - `src/Datagen/Datagen.cpp/.h` and `tune.h` suggest support for **self-play data generation** and parameter tuning.
   - `src/util/preprocess.cpp` likely supports offline preprocessing or code/data generation for these workflows.
   - These paths are separate from the main UCI search loop and are oriented toward engine development rather than game play.

11. **Output and diagnostic paths**
   - The README documents extra engine commands such as `bench`, `d`, and `eval`.
   - These are implemented through the UCI-facing command layer but route into internal diagnostics:
     - board display/state inspection,
     - static evaluation reporting,
     - fixed-depth benchmark searches.

12. **Build and integration surface**
   - The repo is a native C++ project built from source, with a `Makefile` and GitHub Actions workflow under `.github/workflows/build.yaml`.
   - No web backend, database, or network service is part of the architecture; the engine is primarily an embedded compute process driven by text protocol input.

Main entry points: [`src/search.cpp`](https://github.com/rn5f107s2/molybdenum/blob/master/src/search.cpp) (Search), [`src/UCI.cpp`](https://github.com/rn5f107s2/molybdenum/blob/master/src/UCI.cpp) (UCI loop), [`src/Position.cpp`](https://github.com/rn5f107s2/molybdenum/blob/master/src/Position.cpp) (Board state), [`src/Movegen.h`](https://github.com/rn5f107s2/molybdenum/blob/master/src/Movegen.h) (Movegen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Engine runtime"]
  node_n1["Main<br/>entrypoint<br/>[main.cpp]"]
  node_n2["UCI loop<br/>protocol<br/>[UCI.cpp]"]
  node_n3["UCI options<br/>config<br/>[UCIOptions.cpp]"]
  node_n4["Search<br/>[search.cpp]"]
  node_n5["Move ordering<br/>heuristics<br/>[Movepicker.h]"]
  node_n6[("TT cache")]
  node_n7["Time control<br/>timing<br/>[timemanagment.cpp]"]
  node_n8["Threading<br/>parallel search<br/>[thread.cpp]"]
  node_n9["Evaluation<br/>eval core<br/>[eval.h]"]
  node_n10["NNUE<br/>neural eval<br/>[nnue.cpp]"]
end

subgraph group_g2["Core chess model"]
  node_n11["Board state<br/>position model<br/>[Position.cpp]"]
  node_n12["Move data<br/>move model<br/>[Move.h]"]
  node_n13["Bitboards<br/>bitboard primitives<br/>[BitStuff.h]"]
  node_n14["Movegen<br/>move generator<br/>[Movegen.h]"]
  node_n15["Magic tables<br/>attack tables<br/>[MagicBitboards.h]"]
end

subgraph group_g3["Support tooling"]
  node_n16["Perft<br/>validation<br/>[Perft.h]"]
  node_n17["Bench<br/>diagnostic<br/>[bench.h]"]
  node_n18["Datagen<br/>tooling<br/>[Datagen.cpp]"]
  node_n19["Preprocess<br/>tooling<br/>[preprocess.cpp]"]
  node_n20["Build<br/>integration"]
end

node_n1 -->|"starts"| node_n2
node_n2 -->|"options"| node_n3
node_n2 -->|"go/search"| node_n4
node_n2 -->|"position"| node_n11
node_n2 -->|"perft"| node_n16
node_n2 -->|"bench"| node_n17
node_n2 -->|"eval"| node_n9
node_n4 -->|"orders"| node_n5
node_n4 -->|"reads/writes"| node_n6
node_n4 -->|"stops by"| node_n7
node_n4 -->|"parallelizes"| node_n8
node_n4 -->|"consumes"| node_n11
node_n4 -->|"scores"| node_n9
node_n9 -->|"uses"| node_n10
node_n11 -->|"encodes"| node_n12
node_n11 -->|"bitboards"| node_n13
node_n14 -->|"generates for"| node_n11
node_n14 -->|"emits"| node_n12
node_n14 -->|"sliding attacks"| node_n15
node_n16 -->|"validates"| node_n14
node_n17 -->|"drives"| node_n4
node_n18 -->|"samples"| node_n11
node_n18 -->|"self-play"| node_n4
node_n19 -->|"supports"| node_n18
node_n20 -->|"builds"| node_n1
node_n20 -->|"integrates"| node_n4

click node_n1 "https://github.com/rn5f107s2/molybdenum/blob/master/src/main.cpp"
click node_n2 "https://github.com/rn5f107s2/molybdenum/blob/master/src/UCI.cpp"
click node_n3 "https://github.com/rn5f107s2/molybdenum/blob/master/src/UCIOptions.cpp"
click node_n4 "https://github.com/rn5f107s2/molybdenum/blob/master/src/search.cpp"
click node_n5 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Movepicker.h"
click node_n6 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Transpositiontable.cpp"
click node_n7 "https://github.com/rn5f107s2/molybdenum/blob/master/src/timemanagment.cpp"
click node_n8 "https://github.com/rn5f107s2/molybdenum/blob/master/src/thread.cpp"
click node_n9 "https://github.com/rn5f107s2/molybdenum/blob/master/src/eval.h"
click node_n10 "https://github.com/rn5f107s2/molybdenum/blob/master/src/nnue.cpp"
click node_n11 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Position.cpp"
click node_n12 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Move.h"
click node_n13 "https://github.com/rn5f107s2/molybdenum/blob/master/src/BitStuff.h"
click node_n14 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Movegen.h"
click node_n15 "https://github.com/rn5f107s2/molybdenum/blob/master/src/MagicBitboards.h"
click node_n16 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Perft.h"
click node_n17 "https://github.com/rn5f107s2/molybdenum/blob/master/src/bench.h"
click node_n18 "https://github.com/rn5f107s2/molybdenum/blob/master/src/Datagen/Datagen.cpp"
click node_n19 "https://github.com/rn5f107s2/molybdenum/blob/master/src/util/preprocess.cpp"
click node_n20 "https://github.com/rn5f107s2/molybdenum/tree/master/Makefile"

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_n1,node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10 toneBlue
class node_n11,node_n12,node_n13,node_n14,node_n15 toneAmber
class node_n16,node_n17,node_n18,node_n19,node_n20 toneMint
```

## Components

### Engine runtime

Main executable, UCI protocol boundary, and search/evaluation core.

- [Main](https://github.com/rn5f107s2/molybdenum/blob/master/src/main.cpp): entrypoint · Program entry that initializes the engine and starts command handling. · `src/main.cpp`
- [UCI loop](https://github.com/rn5f107s2/molybdenum/blob/master/src/UCI.cpp): protocol · Text command boundary for position, go, bench, eval, and debug commands. · `src/UCI.cpp`
- [UCI options](https://github.com/rn5f107s2/molybdenum/blob/master/src/UCIOptions.cpp): config · Parses and stores engine option settings exposed through UCI. · `src/UCIOptions.cpp`
- [Search](https://github.com/rn5f107s2/molybdenum/blob/master/src/search.cpp): search core · Main thinking loop that scores positions, selects moves, and produces bestmove output. · `src/search.cpp`
- [Move ordering](https://github.com/rn5f107s2/molybdenum/blob/master/src/Movepicker.h): heuristics · Move picker and search utilities used to rank and filter candidate moves. · `src/Movepicker.h`
- [TT cache](https://github.com/rn5f107s2/molybdenum/blob/master/src/Transpositiontable.cpp): cache · Transposition table used to reuse prior search results and speed up pruning. · `src/Transpositiontable.cpp`
- [Time control](https://github.com/rn5f107s2/molybdenum/blob/master/src/timemanagment.cpp): timing · Converts UCI limits into stop conditions for iterative search. · `src/timemanagment.cpp`
- [Threading](https://github.com/rn5f107s2/molybdenum/blob/master/src/thread.cpp): parallel search · Coordinates multi-threaded search execution and shared state. · `src/thread.cpp`
- [Evaluation](https://github.com/rn5f107s2/molybdenum/blob/master/src/eval.h): eval core · Static evaluation path combining neural and positional scoring. · `src/eval.h`
- [NNUE](https://github.com/rn5f107s2/molybdenum/blob/master/src/nnue.cpp): neural eval · Neural-network evaluation implementation and feature pipeline. · `src/nnue.cpp`

### Core chess model

Board state, move representation, and move generation primitives.

- [Board state](https://github.com/rn5f107s2/molybdenum/blob/master/src/Position.cpp): position model · Central chess position representation and state transitions. · `src/Position.cpp`
- [Move data](https://github.com/rn5f107s2/molybdenum/blob/master/src/Move.h): move model · Move encoding and low-level board/move constants. · `src/Move.h`
- [Bitboards](https://github.com/rn5f107s2/molybdenum/blob/master/src/BitStuff.h): bitboard primitives · Bit manipulation helpers and constants used throughout chess logic. · `src/BitStuff.h`
- [Movegen](https://github.com/rn5f107s2/molybdenum/blob/master/src/Movegen.h): move generator · Legal and pseudo-legal move generation built on bitboards and magic tables. · `src/Movegen.h`
- [Magic tables](https://github.com/rn5f107s2/molybdenum/blob/master/src/MagicBitboards.h): attack tables · Precomputed sliding-piece attack generation support. · `src/MagicBitboards.h`

### Support tooling

Diagnostics, tuning, data generation, and build/integration surface.

- [Perft](https://github.com/rn5f107s2/molybdenum/blob/master/src/Perft.h): validation · Move-tree counting used to validate correctness and generator behavior. · `src/Perft.h`
- [Bench](https://github.com/rn5f107s2/molybdenum/blob/master/src/bench.h): diagnostic · Fixed workload benchmark path exposed through the command interface. · `src/bench.h`
- [Datagen](https://github.com/rn5f107s2/molybdenum/blob/master/src/Datagen/Datagen.cpp): tooling · Self-play and data-generation support for engine development. · `src/Datagen/Datagen.cpp`
- [Preprocess](https://github.com/rn5f107s2/molybdenum/blob/master/src/util/preprocess.cpp): tooling · Offline preprocessing utility supporting training or data workflows. · `src/util/preprocess.cpp`
- [Build](https://github.com/rn5f107s2/molybdenum/tree/master/Makefile): integration · Native build and CI integration for compiling and validating the engine. · `Makefile`

## Connections

- Main → UCI loop: starts · Main hands control to the UCI command loop.
- UCI loop → UCI options: options · UCI exposes and updates engine settings.
- UCI loop → Search: go/search · Search is launched in response to go-like commands.
- UCI loop → Board state: position · Command layer creates or mutates board state.
- UCI loop → Perft: perft · Diagnostic commands can route to move-tree validation.
- UCI loop → Bench: bench · Benchmark command triggers fixed-depth search workload.
- UCI loop → Evaluation: eval · Evaluation diagnostics query the static eval layer.
- Search → Move ordering: orders · Search uses move ordering heuristics.
- Search → TT cache: reads/writes · Search probes and stores positions in the transposition table.
- Search → Time control: stops by · Time control determines when search must stop.
- Search → Threading: parallelizes · Search can run across multiple threads.
- Search → Board state: consumes · Search operates on the current position.
- Search → Evaluation: scores · Leaf or quiescent positions are evaluated.
- Evaluation → NNUE: uses · Evaluation includes the NNUE path.
- Board state → Move data: encodes · Board state relies on the engine's move representation.
- Board state → Bitboards: bitboards · Position internals use bitboard primitives.
- Movegen → Board state: generates for · Move generation derives legal moves from position state.
- Movegen → Move data: emits · Generated moves use the shared move encoding.
- Movegen → Magic tables: sliding attacks · Magic bitboards supply fast rook/bishop attack lookups.
- Perft → Movegen: validates · Perft depends on the move generator for tree counts.
- Bench → Search: drives · Benchmarking exercises the search core.
- Datagen → Board state: samples · Data generation works from engine positions.
- Datagen → Search: self-play · Generated data can be produced via engine search.
- Preprocess → Datagen: supports · Preprocessing feeds the data-generation workflow.
- Build → Main: builds · Build surface compiles the executable entrypoint.
- Build → Search: integrates · CI and build tooling validate the search engine.
