# pgg106/alexandria architecture

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

- Interactive diagram: https://gitdiagram.com/pgg106/alexandria
- Repository: https://github.com/pgg106/alexandria

## Overview

Alexandria is a UCI chess engine. A chess GUI or other UCI client sends commands; the engine parses positions and search limits, searches legal continuations, evaluates positions, and reports a best move and analysis. The runtime also supports move-generation/perft work and a neural-network evaluator; the README documents UCI compatibility and an externally downloaded network. The graph follows relationships visible in the README and source index; unsampled implementation details are not inferred.

Main entry points: [`src/search.cpp`](https://github.com/pgg106/alexandria/blob/master/src/search.cpp) (Position search), [`src/uci.cpp`](https://github.com/pgg106/alexandria/blob/master/src/uci.cpp) (UCI command loop), [`src/position.cpp`](https://github.com/pgg106/alexandria/blob/master/src/position.cpp) (Board position), [`src/movegen.cpp`](https://github.com/pgg106/alexandria/blob/master/src/movegen.cpp) (Legal move generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["UCI interface"]
  node_uci["UCI command loop<br/>[uci.cpp]"]
  node_io["Engine I/O<br/>[io.cpp]"]
end

subgraph group_chess["Chess state and moves"]
  node_position["Board position<br/>[position.cpp]"]
  node_movegen["Legal move generation<br/>[movegen.cpp]"]
  node_makemove["Move application<br/>[makemove.cpp]"]
  node_attacks["Attack tables<br/>[attack.cpp]"]
  node_perft["Perft<br/>[perft.cpp]"]
end

subgraph group_search["Search and evaluation"]
  node_search["Position search<br/>[search.cpp]"]
  node_picker["Move ordering<br/>[movepicker.cpp]"]
  node_history["Search heuristics<br/>[history.cpp]"]
  node_tt[("Transposition table<br/>[ttable.cpp]")]
  node_timing["Time management<br/>[time_manager.cpp]"]
  node_eval["Classical evaluation<br/>[eval.h]"]
  node_nnue["NNUE evaluation<br/>[nnue.cpp]"]
end

subgraph group_runtime["Engine runtime"]
  node_entry["Program entry<br/>[main.cpp]"]
  node_threads["Search threads<br/>[threads.h]"]
  node_init["Engine initialization<br/>[init.cpp]"]
end

node_client(("UCI client"))
node_network["Neural network file"]

node_client -->|"sends UCI commands"| node_uci
node_entry -->|"initializes"| node_init
node_entry -->|"starts loop"| node_uci
node_uci -->|"parses positions"| node_position
node_uci -->|"starts search"| node_search
node_uci -->|"sets search limits"| node_timing
node_uci -->|"configures hash"| node_tt
node_uci -->|"uses for commands"| node_movegen
node_uci -->|"uses output"| node_io
node_io -.->|"reports results"| node_client
node_position -->|"parses move sequences"| node_makemove
node_position -->|"updates check state"| node_attacks
node_movegen -->|"queries attacks"| node_attacks
node_movegen -->|"reads board state"| node_position
node_movegen -->|"tests moves"| node_makemove
node_search -->|"searches position"| node_position
node_search -->|"generates moves"| node_movegen
node_search -->|"orders moves"| node_picker
node_search -->|"uses heuristics"| node_history
node_search -->|"probes and stores"| node_tt
node_search -->|"checks limits"| node_timing
node_search -->|"evaluates positions"| node_eval
node_search -->|"uses thread data"| node_threads
node_eval -->|"reads position"| node_position
node_position -->|"maintains accumulators"| node_nnue
node_nnue -->|"evaluates features"| node_position
node_nnue -->|"loads network data"| node_network
node_uci -->|"dispatches perft"| node_perft
node_init -->|"initializes chess state"| node_position
node_init -->|"initializes table"| node_tt
node_init -->|"initializes threads"| node_threads

click node_entry "https://github.com/pgg106/alexandria/blob/master/src/main.cpp"
click node_uci "https://github.com/pgg106/alexandria/blob/master/src/uci.cpp"
click node_io "https://github.com/pgg106/alexandria/blob/master/src/io.cpp"
click node_position "https://github.com/pgg106/alexandria/blob/master/src/position.cpp"
click node_movegen "https://github.com/pgg106/alexandria/blob/master/src/movegen.cpp"
click node_makemove "https://github.com/pgg106/alexandria/blob/master/src/makemove.cpp"
click node_attacks "https://github.com/pgg106/alexandria/blob/master/src/attack.cpp"
click node_perft "https://github.com/pgg106/alexandria/blob/master/src/perft.cpp"
click node_search "https://github.com/pgg106/alexandria/blob/master/src/search.cpp"
click node_picker "https://github.com/pgg106/alexandria/blob/master/src/movepicker.cpp"
click node_history "https://github.com/pgg106/alexandria/blob/master/src/history.cpp"
click node_tt "https://github.com/pgg106/alexandria/blob/master/src/ttable.cpp"
click node_timing "https://github.com/pgg106/alexandria/blob/master/src/time_manager.cpp"
click node_eval "https://github.com/pgg106/alexandria/blob/master/src/eval.h"
click node_nnue "https://github.com/pgg106/alexandria/blob/master/src/nnue.cpp"
click node_threads "https://github.com/pgg106/alexandria/blob/master/src/threads.h"
click node_init "https://github.com/pgg106/alexandria/blob/master/src/init.cpp"

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_uci,node_io,node_client toneBlue
class node_position,node_movegen,node_makemove,node_attacks,node_perft toneAmber
class node_search,node_picker,node_history,node_tt,node_timing,node_eval,node_nnue toneMint
class node_entry,node_threads,node_init toneRose
class node_network toneIndigo
```

## Components

### UCI interface

- [UCI command loop](https://github.com/pgg106/alexandria/blob/master/src/uci.cpp): `src/uci.cpp`
- [Engine I/O](https://github.com/pgg106/alexandria/blob/master/src/io.cpp): `src/io.cpp`

### Chess state and moves

- [Board position](https://github.com/pgg106/alexandria/blob/master/src/position.cpp): `src/position.cpp`
- [Legal move generation](https://github.com/pgg106/alexandria/blob/master/src/movegen.cpp): `src/movegen.cpp`
- [Move application](https://github.com/pgg106/alexandria/blob/master/src/makemove.cpp): `src/makemove.cpp`
- [Attack tables](https://github.com/pgg106/alexandria/blob/master/src/attack.cpp): `src/attack.cpp`
- [Perft](https://github.com/pgg106/alexandria/blob/master/src/perft.cpp): `src/perft.cpp`

### Search and evaluation

- [Position search](https://github.com/pgg106/alexandria/blob/master/src/search.cpp): `src/search.cpp`
- [Move ordering](https://github.com/pgg106/alexandria/blob/master/src/movepicker.cpp): `src/movepicker.cpp`
- [Search heuristics](https://github.com/pgg106/alexandria/blob/master/src/history.cpp): `src/history.cpp`
- [Transposition table](https://github.com/pgg106/alexandria/blob/master/src/ttable.cpp): `src/ttable.cpp`
- [Time management](https://github.com/pgg106/alexandria/blob/master/src/time_manager.cpp): `src/time_manager.cpp`
- [Classical evaluation](https://github.com/pgg106/alexandria/blob/master/src/eval.h): `src/eval.h`
- [NNUE evaluation](https://github.com/pgg106/alexandria/blob/master/src/nnue.cpp): `src/nnue.cpp`

### Engine runtime

- [Program entry](https://github.com/pgg106/alexandria/blob/master/src/main.cpp): `src/main.cpp`
- [Search threads](https://github.com/pgg106/alexandria/blob/master/src/threads.h): `src/threads.h`
- [Engine initialization](https://github.com/pgg106/alexandria/blob/master/src/init.cpp): `src/init.cpp`

### Other components

- **UCI client**
- **Neural network file**

## Connections

- UCI client → UCI command loop: sends UCI commands (evidence: `README.md`)
- Program entry → Engine initialization: initializes (evidence: `src/main.cpp`)
- Program entry → UCI command loop: starts loop (evidence: `src/main.cpp`)
- UCI command loop → Board position: parses positions (evidence: `src/uci.cpp`)
- UCI command loop → Position search: starts search (evidence: `src/uci.cpp`)
- UCI command loop → Time management: sets search limits (evidence: `src/uci.cpp`)
- UCI command loop → Transposition table: configures hash (evidence: `src/uci.cpp`)
- UCI command loop → Legal move generation: uses for commands (evidence: `src/uci.cpp`)
- UCI command loop → Engine I/O: uses output (evidence: `src/uci.cpp`)
- Engine I/O → UCI client: reports results
- Board position → Move application: parses move sequences (evidence: `src/position.cpp`)
- Board position → Attack tables: updates check state (evidence: `src/position.cpp`)
- Legal move generation → Attack tables: queries attacks (evidence: `src/movegen.cpp`)
- Legal move generation → Board position: reads board state (evidence: `src/movegen.cpp`)
- Legal move generation → Move application: tests moves (evidence: `src/movegen.cpp`)
- Position search → Board position: searches position (evidence: `src/search.cpp`)
- Position search → Legal move generation: generates moves (evidence: `src/search.cpp`)
- Position search → Move ordering: orders moves (evidence: `src/search.cpp`)
- Position search → Search heuristics: uses heuristics (evidence: `src/search.cpp`)
- Position search → Transposition table: probes and stores (evidence: `src/search.cpp`)
- Position search → Time management: checks limits (evidence: `src/search.cpp`)
- Position search → Classical evaluation: evaluates positions (evidence: `src/search.cpp`)
- Position search → Search threads: uses thread data (evidence: `src/search.cpp`)
- Classical evaluation → Board position: reads position (evidence: `src/eval.h`)
- Board position → NNUE evaluation: maintains accumulators
- NNUE evaluation → Board position: evaluates features (evidence: `src/nnue.cpp`)
- NNUE evaluation → Neural network file: loads network data (evidence: `README.md`)
- UCI command loop → Perft: dispatches perft (evidence: `src/uci.cpp`)
- Engine initialization → Board position: initializes chess state (evidence: `src/init.cpp`)
- Engine initialization → Transposition table: initializes table (evidence: `src/init.cpp`)
- Engine initialization → Search threads: initializes threads (evidence: `src/init.cpp`)
