# robot1273/cpp-chess architecture

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

- Interactive diagram: https://gitdiagram.com/robot1273/cpp-chess
- Repository: https://github.com/robot1273/cpp-chess

## Overview

This repository is a C++ chess engine with terminal-play and UCI entry points. The main workflow is a player or chess GUI submitting a position and requesting a move; the runner updates the board, asks the searcher to choose a move, and returns it through the selected interface. Internally, board state and legal-move generation support search, which uses evaluation and a transposition table. The source excerpts show these core relationships; benchmark and perft modes are also present, but their full wiring is only partly sampled.

Main entry points: [`src/bot/search.cpp`](https://github.com/robot1273/cpp-chess/blob/main/src/bot/search.cpp) (Move search), [`src/run.cpp`](https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp) (UCI adapter), [`src/board/board.hpp`](https://github.com/robot1273/cpp-chess/blob/main/src/board/board.hpp) (Board state), [`src/board/board_movegen.cpp`](https://github.com/robot1273/cpp-chess/blob/main/src/board/board_movegen.cpp) (Legal move generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces and modes"]
  node_main["Process entry<br/>[main.cpp]"]
  node_runner["Game runner<br/>[run.cpp]"]
  node_uci_adapter["UCI adapter<br/>[run.cpp]"]
  node_terminal["Terminal play<br/>[run.cpp]"]
  node_bench_perft["Benchmark and perft<br/>[run.cpp]"]
end

subgraph group_chess_core["Chess rules and state"]
  node_board["Board state<br/>[board.hpp]"]
  node_board_updates["State and play"]
  node_movegen["Legal move generation<br/>[board_movegen.cpp]"]
end

subgraph group_engine["Search engine"]
  node_search["Move search<br/>[search.cpp]"]
  node_evaluation["Position evaluation<br/>[evaluation.cpp]"]
end

subgraph group_internals["Engine internals"]
  node_transposition[("Transposition table<br/>[search.hpp]")]
  node_precalculation["Attack tables"]
end

node_player(("Player"))
node_uci_gui(("UCI GUI"))

node_player -->|"plays moves"| node_terminal
node_uci_gui -->|"sends commands"| node_uci_adapter
node_main -->|"dispatches mode"| node_runner
node_runner -->|"runs play"| node_terminal
node_runner -->|"runs UCI"| node_uci_adapter
node_runner -->|"runs analysis mode"| node_bench_perft
node_terminal -->|"updates position"| node_board
node_terminal -->|"requests move"| node_search
node_uci_adapter -->|"loads position"| node_board
node_uci_adapter -->|"requests move"| node_search
node_uci_adapter -->|"returns move"| node_uci_gui
node_search -->|"generates legal moves"| node_movegen
node_search -->|"simulates moves"| node_board
node_search -->|"scores positions"| node_evaluation
node_search -->|"probes and stores"| node_transposition
node_board -->|"updates state"| node_board_updates
node_movegen -->|"reads attack tables"| node_precalculation
node_bench_perft -->|"loads test positions"| node_board
node_bench_perft -->|"measures search"| node_search

click node_main "https://github.com/robot1273/cpp-chess/blob/main/src/main.cpp"
click node_runner "https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp"
click node_uci_adapter "https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp"
click node_terminal "https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp"
click node_bench_perft "https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp"
click node_board "https://github.com/robot1273/cpp-chess/blob/main/src/board/board.hpp"
click node_board_updates "https://github.com/robot1273/cpp-chess/blob/main/src/board/board_state_and_play.cpp"
click node_movegen "https://github.com/robot1273/cpp-chess/blob/main/src/board/board_movegen.cpp"
click node_search "https://github.com/robot1273/cpp-chess/blob/main/src/bot/search.cpp"
click node_evaluation "https://github.com/robot1273/cpp-chess/blob/main/src/bot/evaluation.cpp"
click node_transposition "https://github.com/robot1273/cpp-chess/blob/main/src/bot/search.hpp"
click node_precalculation "https://github.com/robot1273/cpp-chess/blob/main/src/board/board_precalculation.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_main,node_runner,node_uci_adapter,node_terminal,node_bench_perft,node_uci_gui toneBlue
class node_board,node_board_updates,node_movegen toneAmber
class node_search,node_evaluation toneMint
class node_transposition,node_precalculation toneRose
class node_player toneIndigo
```

## Components

### Interfaces and modes

- [Process entry](https://github.com/robot1273/cpp-chess/blob/main/src/main.cpp): `src/main.cpp`
- [Game runner](https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp): `src/run.cpp`
- [UCI adapter](https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp): `src/run.cpp`
- [Terminal play](https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp): `src/run.cpp`
- [Benchmark and perft](https://github.com/robot1273/cpp-chess/blob/main/src/run.cpp): `src/run.cpp`

### Chess rules and state

- [Board state](https://github.com/robot1273/cpp-chess/blob/main/src/board/board.hpp): `src/board/board.hpp`
- [State and play](https://github.com/robot1273/cpp-chess/blob/main/src/board/board_state_and_play.cpp): `src/board/board_state_and_play.cpp`
- [Legal move generation](https://github.com/robot1273/cpp-chess/blob/main/src/board/board_movegen.cpp): `src/board/board_movegen.cpp`

### Search engine

- [Move search](https://github.com/robot1273/cpp-chess/blob/main/src/bot/search.cpp): `src/bot/search.cpp`
- [Position evaluation](https://github.com/robot1273/cpp-chess/blob/main/src/bot/evaluation.cpp): `src/bot/evaluation.cpp`

### Engine internals

- [Transposition table](https://github.com/robot1273/cpp-chess/blob/main/src/bot/search.hpp): `src/bot/search.hpp`
- [Attack tables](https://github.com/robot1273/cpp-chess/blob/main/src/board/board_precalculation.cpp): `src/board/board_precalculation.cpp`

### Other components

- **Player**
- **UCI GUI**

## Connections

- Player → Terminal play: plays moves
- UCI GUI → UCI adapter: sends commands
- Process entry → Game runner: dispatches mode
- Game runner → Terminal play: runs play
- Game runner → UCI adapter: runs UCI
- Game runner → Benchmark and perft: runs analysis mode
- Terminal play → Board state: updates position
- Terminal play → Move search: requests move
- UCI adapter → Board state: loads position
- UCI adapter → Move search: requests move
- UCI adapter → UCI GUI: returns move
- Move search → Legal move generation: generates legal moves
- Move search → Board state: simulates moves
- Move search → Position evaluation: scores positions
- Move search → Transposition table: probes and stores
- Board state → State and play: updates state
- Legal move generation → Attack tables: reads attack tables
- Benchmark and perft → Board state: loads test positions
- Benchmark and perft → Move search: measures search