# dheirav/chessbot architecture

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

- Interactive diagram: https://gitdiagram.com/dheirav/chessbot
- Repository: https://github.com/dheirav/chessbot

## Overview

ChessBot is a local chess-playing and analysis application with graphical, terminal-coach, and UCI entry modes. In the main game workflow, a player enters moves through the GUI; game management validates and records them, requests an engine search when appropriate, and applies the returned move. The engine’s search uses chess rules, evaluation, ordering, and cached positions to choose a move. The README also documents PGN export, clocks, undo/redo, terminal detection, and UCI controls. Some subsystem links reflect README capabilities; unsampled implementations are not inferred beyond those documented roles.

Main entry points: [`src/game_manager.cpp`](https://github.com/dheirav/chessbot/blob/main/src/game_manager.cpp) (Game coordinator), [`src/engine/search.cpp`](https://github.com/dheirav/chessbot/blob/main/src/engine/search.cpp) (Search), [`src/main.cpp`](https://github.com/dheirav/chessbot/blob/main/src/main.cpp) (Mode selection), [`src/gui_manager.cpp`](https://github.com/dheirav/chessbot/blob/main/src/gui_manager.cpp) (Window manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application modes"]
  node_main["Mode selection<br/>[main.cpp]"]
  node_coach["Coach mode<br/>[coach.cpp]"]
  node_uci["UCI protocol<br/>[uci.cpp]"]
end

subgraph group_game["Game interaction"]
  node_gui["Window manager<br/>[gui_manager.cpp]"]
  node_input["Board input<br/>[input.cpp]"]
  node_renderer["Board and HUD<br/>[renderer.cpp]"]
  node_game_manager["Game coordinator<br/>[game_manager.cpp]"]
  node_pgn["PGN export<br/>[pgn.cpp]"]
end

subgraph group_rules["Chess position"]
  node_board["Board state<br/>[board.cpp]"]
  node_movegen["Move generation<br/>[movegen.cpp]"]
  node_validator["Legal move checks"]
  node_fen["FEN positions<br/>[fen.cpp]"]
end

subgraph group_engine["Engine search"]
  node_engine_impl["Engine adapter"]
  node_search["Search<br/>[search.cpp]"]
  node_evaluation["Position evaluation<br/>[evaluation.cpp]"]
  node_ordering["Move ordering<br/>[move_ordering.cpp]"]
  node_tt[("Transposition table")]
end

node_player(("Player"))
node_uci_client(("UCI client"))

node_player -->|"starts app"| node_main
node_uci_client -->|"selects UCI"| node_main
node_main -->|"starts GUI"| node_gui
node_main -->|"runs coach"| node_coach
node_main -->|"runs protocol"| node_uci
node_player -->|"plays moves"| node_gui
node_gui -->|"routes events"| node_input
node_gui -->|"updates game"| node_game_manager
node_input -->|"submits moves"| node_game_manager
node_game_manager -->|"supplies game view"| node_renderer
node_game_manager -->|"updates position"| node_board
node_game_manager -->|"checks legality"| node_validator
node_game_manager -->|"requests search"| node_engine_impl
node_game_manager -->|"exports game"| node_pgn
node_uci -->|"controls engine"| node_engine_impl
node_engine_impl -->|"searches position"| node_search
node_search -->|"generates moves"| node_movegen
node_search -->|"scores positions"| node_evaluation
node_search -->|"orders moves"| node_ordering
node_search -->|"probes and stores"| node_tt
node_movegen -->|"reads position"| node_board
node_validator -->|"checks position"| node_board
node_fen -->|"loads position"| node_board
node_coach -->|"advises game"| node_game_manager

click node_main "https://github.com/dheirav/chessbot/blob/main/src/main.cpp"
click node_coach "https://github.com/dheirav/chessbot/blob/main/src/coach.cpp"
click node_uci "https://github.com/dheirav/chessbot/blob/main/src/engine/uci.cpp"
click node_gui "https://github.com/dheirav/chessbot/blob/main/src/gui_manager.cpp"
click node_input "https://github.com/dheirav/chessbot/blob/main/src/gui/input.cpp"
click node_renderer "https://github.com/dheirav/chessbot/blob/main/src/gui/renderer.cpp"
click node_game_manager "https://github.com/dheirav/chessbot/blob/main/src/game_manager.cpp"
click node_pgn "https://github.com/dheirav/chessbot/blob/main/src/engine/pgn.cpp"
click node_board "https://github.com/dheirav/chessbot/blob/main/src/engine/board.cpp"
click node_movegen "https://github.com/dheirav/chessbot/blob/main/src/engine/movegen.cpp"
click node_validator "https://github.com/dheirav/chessbot/blob/main/src/engine/legal_move_validator.cpp"
click node_fen "https://github.com/dheirav/chessbot/blob/main/src/engine/fen.cpp"
click node_engine_impl "https://github.com/dheirav/chessbot/blob/main/src/engine/chessbot_engine.cpp"
click node_search "https://github.com/dheirav/chessbot/blob/main/src/engine/search.cpp"
click node_evaluation "https://github.com/dheirav/chessbot/blob/main/src/engine/evaluation.cpp"
click node_ordering "https://github.com/dheirav/chessbot/blob/main/src/engine/move_ordering.cpp"
click node_tt "https://github.com/dheirav/chessbot/blob/main/src/engine/transposition_table.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_coach,node_uci,node_uci_client toneBlue
class node_gui,node_input,node_renderer,node_game_manager,node_pgn toneAmber
class node_board,node_movegen,node_validator,node_fen toneMint
class node_engine_impl,node_search,node_evaluation,node_ordering,node_tt toneRose
class node_player toneIndigo
```

## Components

### Application modes

- [Mode selection](https://github.com/dheirav/chessbot/blob/main/src/main.cpp): `src/main.cpp`
- [Coach mode](https://github.com/dheirav/chessbot/blob/main/src/coach.cpp): `src/coach.cpp`
- [UCI protocol](https://github.com/dheirav/chessbot/blob/main/src/engine/uci.cpp): `src/engine/uci.cpp`

### Game interaction

- [Window manager](https://github.com/dheirav/chessbot/blob/main/src/gui_manager.cpp): `src/gui_manager.cpp`
- [Board input](https://github.com/dheirav/chessbot/blob/main/src/gui/input.cpp): `src/gui/input.cpp`
- [Board and HUD](https://github.com/dheirav/chessbot/blob/main/src/gui/renderer.cpp): `src/gui/renderer.cpp`
- [Game coordinator](https://github.com/dheirav/chessbot/blob/main/src/game_manager.cpp): `src/game_manager.cpp`
- [PGN export](https://github.com/dheirav/chessbot/blob/main/src/engine/pgn.cpp): `src/engine/pgn.cpp`

### Chess position

- [Board state](https://github.com/dheirav/chessbot/blob/main/src/engine/board.cpp): `src/engine/board.cpp`
- [Move generation](https://github.com/dheirav/chessbot/blob/main/src/engine/movegen.cpp): `src/engine/movegen.cpp`
- [Legal move checks](https://github.com/dheirav/chessbot/blob/main/src/engine/legal_move_validator.cpp): `src/engine/legal_move_validator.cpp`
- [FEN positions](https://github.com/dheirav/chessbot/blob/main/src/engine/fen.cpp): `src/engine/fen.cpp`

### Engine search

- [Engine adapter](https://github.com/dheirav/chessbot/blob/main/src/engine/chessbot_engine.cpp): `src/engine/chessbot_engine.cpp`
- [Search](https://github.com/dheirav/chessbot/blob/main/src/engine/search.cpp): `src/engine/search.cpp`
- [Position evaluation](https://github.com/dheirav/chessbot/blob/main/src/engine/evaluation.cpp): `src/engine/evaluation.cpp`
- [Move ordering](https://github.com/dheirav/chessbot/blob/main/src/engine/move_ordering.cpp): `src/engine/move_ordering.cpp`
- [Transposition table](https://github.com/dheirav/chessbot/blob/main/src/engine/transposition_table.cpp): `src/engine/transposition_table.cpp`

### Other components

- **Player**
- **UCI client**

## Connections

- Player → Mode selection: starts app
- UCI client → Mode selection: selects UCI
- Mode selection → Window manager: starts GUI
- Mode selection → Coach mode: runs coach
- Mode selection → UCI protocol: runs protocol
- Player → Window manager: plays moves
- Window manager → Board input: routes events
- Window manager → Game coordinator: updates game
- Board input → Game coordinator: submits moves
- Game coordinator → Board and HUD: supplies game view
- Game coordinator → Board state: updates position
- Game coordinator → Legal move checks: checks legality
- Game coordinator → Engine adapter: requests search
- Game coordinator → PGN export: exports game
- UCI protocol → Engine adapter: controls engine
- Engine adapter → Search: searches position
- Search → Move generation: generates moves
- Search → Position evaluation: scores positions
- Search → Move ordering: orders moves
- Search → Transposition table: probes and stores
- Move generation → Board state: reads position
- Legal move checks → Board state: checks position
- FEN positions → Board state: loads position
- Coach mode → Game coordinator: advises game