# merzlikin-matvey/chess architecture

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

- Interactive diagram: https://gitdiagram.com/merzlikin-matvey/chess
- Repository: https://github.com/merzlikin-matvey/chess

## Overview

1. **What this repository is**
   - A C++ chess engine/library with multiple entry points: a reusable core library, a UCI command-line engine, test/perft binaries, examples, and a WASM-targeted demo.
   - The code is organized around bitboard-based move generation and a search/evaluation pipeline.

2. **Public API boundary**
   - `include/chess-lib.hpp` is the main umbrella header for consumers.
   - The `include/headers/` subtree exposes the engine’s public types and subsystems: board state, moves, notation, FEN, UCI, AI/search, transposition table, Zobrist hashing, masks, and constants.

3. **Board and game-state subsystem**
   - `src/board/` and `include/headers/board.hpp` implement the mutable chess position model.
   - This layer handles core state transitions such as:
     - initializing and ending a game,
     - parsing/serializing FEN,
     - move legality and check/checkmate detection,
     - history tracking,
     - output/pretty-printing of positions.
   - This is the central state boundary used by both the engine and the tools/tests.

4. **Move representation and notation**
   - `move`, `move_array`, and `notations` define how moves are stored, manipulated, and converted to human-readable or protocol formats.
   - These modules sit between board state and consumers like UCI, tests, and examples.

5. **Bitboard-based move generation**
   - The engine uses bitboards heavily, with masks and bit operations isolated under `include/headers/masks/`, `bitboard_operations.hpp`, and `bitboard_lines.hpp`.
   - Piece-specific attack/move masks exist for pawns, kings/knights, bishops, and rooks.
   - Sliding-piece support is optimized through magic-bitboard infrastructure:
     - `magic_numbers_constants.hpp`
     - `magic_numbers_generators/*`
     - precomputed attack tables/masks for bishops, rooks, and pin directions.
   - This is the main low-level performance subsystem feeding legal move generation.

6. **Legal move generation pipeline**
   - `src/board/get_legal_moves.cpp` is the main boundary where pseudo-legal attacks, pin/check constraints, and board state combine into legal moves.
   - Supporting files such as `check_and_checkmate.cpp` and the various pin-mask headers show that legality is enforced with attack maps and pin analysis rather than a high-level search-only filter.

7. **Search and evaluation subsystem**
   - `src/ai/` contains the engine’s decision-making stack:
     - `minimax.cpp` for search,
     - `quiescence.cpp` for tactical extension,
     - `move_sorting.cpp` for ordering,
     - `evaluate_position.cpp` for static evaluation.
   - Evaluation is driven by `pst.hpp` and `evaluating_constants.hpp`, indicating piece-square tables and tuned heuristics.
   - `ai.hpp` is the public interface for invoking search.

8. **Search state and pruning support**
   - `zobrist.hpp/.cpp` and `transposition_table.hpp` provide position hashing and cached search results.
   - These are used to avoid re-evaluating repeated positions and to speed up alpha-beta style search.
   - Together with move ordering, they form the core performance layer above legal move generation.

9. **Protocol and interface layer**
   - `src/uci.cpp` plus `uci/main.cpp` implement the UCI engine interface, so external chess GUIs can talk to the engine.
   - This layer translates protocol commands into board updates and search calls, then emits best moves and status text.
   - `example/`, `stateless-example/`, and `wasm-html-example/` show alternative integration paths:
     - embedding the library in a C++ app,
     - using it without persistent engine state,
     - driving it from a browser/WASM target.

10. **Validation and benchmarking**
   - `tests/legal_moves/` contains JSON fixtures for move-legality regression coverage across starting positions, openings, promotions, castling, checks/checkmates, and stalemates.
   - `performance/tests/perft.cpp` validates move generation by counting legal move trees; `performance/tests/alpha_beta.cpp` benchmarks search behavior.
   - This means correctness is checked both at the move-generator boundary and at the search boundary.

11. **Build and deployment structure**
   - The project is CMake-driven at the root, with separate CMake targets for the library, UCI binary, tests, performance tools, and examples.
   - `scripts/wasm.sh` and the WASM HTML example indicate a specialized browser build path, separate from the native CLI/test workflow.

12. **End-to-end data flow**
   - Typical engine flow is:
     - input position via FEN or UCI,
     - board state updated,
     - legal moves generated from bitboards/masks,
     - search explores moves with evaluation, quiescence, and transposition-table lookup,
     - best move returned through UCI or example output.
   - Perft and legal-move tests reuse the same board/move-generation core, which helps ensure the engine’s correctness across both interactive and benchmark modes.

Main entry points: [`src/board`](https://github.com/merzlikin-matvey/chess/tree/main/src/board) (Board), [`include/headers`](https://github.com/merzlikin-matvey/chess/tree/main/include/headers) (Engine API), [`src/ai`](https://github.com/merzlikin-matvey/chess/tree/main/src/ai) (Search), [`src/board/get_legal_moves.cpp`](https://github.com/merzlikin-matvey/chess/blob/main/src/board/get_legal_moves.cpp) (Legal moves)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_include_chess_lib["chess-lib.hpp<br/>umbrella header<br/>[chess-lib.hpp]"]
  node_public_headers["Engine API<br/>public headers"]
end

subgraph group_core_state["Core State"]
  node_board_module["Board<br/>state model"]
  node_fen_module["FEN<br/>serialization<br/>[fen.cpp]"]
  node_move_types["Moves<br/>representation<br/>[move.cpp]"]
  node_notations_module["Notation<br/>conversion<br/>[notations.cpp]"]
  node_legal_moves["Legal moves<br/>move generation"]
end

subgraph group_low_level["Bitboards"]
  node_masks_module["Masks"]
  node_bitboard_ops["Bit ops<br/>bitboard ops"]
  node_magic_tables[("Magic tables<br/>sliding attacks")]
  node_magic_generators["Magic gen<br/>table generation"]
end

subgraph group_search["Search"]
  node_zobrist_tt[("Hashing<br/>search state<br/>[zobrist.cpp]")]
  node_ai_api["AI API<br/>search entry<br/>[ai.hpp]"]
  node_search_core["Search<br/>alpha-beta"]
  node_evaluation["Eval"]
end

subgraph group_interfaces["Interfaces"]
  node_uci_interface["UCI<br/>protocol layer<br/>[uci.cpp]"]
  node_examples["Examples<br/>integration samples"]
end

subgraph group_validation["Validation"]
  node_tests_perf["Tests & perf<br/>validation"]
end

node_include_chess_lib -->|"re-exports"| node_public_headers
node_public_headers -->|"exposes"| node_board_module
node_public_headers -->|"exposes"| node_move_types
node_public_headers -->|"exposes"| node_notations_module
node_public_headers -->|"exposes"| node_ai_api
node_board_module -->|"uses"| node_fen_module
node_board_module -->|"updates"| node_move_types
node_board_module -->|"feeds"| node_legal_moves
node_legal_moves -->|"depends on"| node_masks_module
node_legal_moves -->|"depends on"| node_bitboard_ops
node_masks_module -->|"uses"| node_magic_tables
node_magic_generators -->|"produces"| node_magic_tables
node_ai_api -->|"invokes"| node_search_core
node_search_core -->|"scores with"| node_evaluation
node_search_core -->|"caches with"| node_zobrist_tt
node_search_core -->|"expands"| node_legal_moves
node_evaluation -->|"reads"| node_board_module
node_uci_interface -->|"drives"| node_board_module
node_uci_interface -->|"queries"| node_ai_api
node_uci_interface -->|"formats"| node_notations_module
node_examples -->|"embeds"| node_board_module
node_examples -->|"embeds"| node_ai_api
node_tests_perf -->|"validates"| node_legal_moves
node_tests_perf -->|"benchmarks"| node_search_core

click node_include_chess_lib "https://github.com/merzlikin-matvey/chess/blob/main/include/chess-lib.hpp"
click node_public_headers "https://github.com/merzlikin-matvey/chess/tree/main/include/headers"
click node_board_module "https://github.com/merzlikin-matvey/chess/tree/main/src/board"
click node_fen_module "https://github.com/merzlikin-matvey/chess/blob/main/src/board/fen.cpp"
click node_move_types "https://github.com/merzlikin-matvey/chess/blob/main/src/move.cpp"
click node_notations_module "https://github.com/merzlikin-matvey/chess/blob/main/src/notations.cpp"
click node_masks_module "https://github.com/merzlikin-matvey/chess/tree/main/include/headers/masks"
click node_bitboard_ops "https://github.com/merzlikin-matvey/chess/blob/main/include/headers/bitboard_operations.hpp"
click node_magic_tables "https://github.com/merzlikin-matvey/chess/blob/main/include/headers/magic_numbers_constants.hpp"
click node_magic_generators "https://github.com/merzlikin-matvey/chess/tree/main/src/magic_numbers_generators"
click node_legal_moves "https://github.com/merzlikin-matvey/chess/blob/main/src/board/get_legal_moves.cpp"
click node_zobrist_tt "https://github.com/merzlikin-matvey/chess/blob/main/src/zobrist.cpp"
click node_ai_api "https://github.com/merzlikin-matvey/chess/blob/main/include/headers/ai.hpp"
click node_search_core "https://github.com/merzlikin-matvey/chess/tree/main/src/ai"
click node_evaluation "https://github.com/merzlikin-matvey/chess/blob/main/src/ai/evaluate_position.cpp"
click node_uci_interface "https://github.com/merzlikin-matvey/chess/blob/main/src/uci.cpp"
click node_examples "https://github.com/merzlikin-matvey/chess/tree/main/example"
click node_tests_perf "https://github.com/merzlikin-matvey/chess/tree/main/tests"

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_include_chess_lib,node_public_headers toneBlue
class node_board_module,node_fen_module,node_move_types,node_notations_module,node_legal_moves toneAmber
class node_masks_module,node_bitboard_ops,node_magic_tables,node_magic_generators toneMint
class node_zobrist_tt,node_ai_api,node_search_core,node_evaluation toneRose
class node_uci_interface,node_examples toneIndigo
class node_tests_perf toneTeal
```

## Components

### Public API

Umbrella and exported headers for consumers

- [chess-lib.hpp](https://github.com/merzlikin-matvey/chess/blob/main/include/chess-lib.hpp): umbrella header · Main public include for library consumers · `include/chess-lib.hpp`
- [Engine API](https://github.com/merzlikin-matvey/chess/tree/main/include/headers): public headers · Exported board, moves, UCI, hashing, and evaluation interfaces · `include/headers`

### Core State

Board model, FEN, moves, and notation

- [Board](https://github.com/merzlikin-matvey/chess/tree/main/src/board): state model · Mutable chess position and core game-state transitions · `src/board`
- [FEN](https://github.com/merzlikin-matvey/chess/blob/main/src/board/fen.cpp): serialization · Position parsing and serialization · `src/board/fen.cpp`
- [Moves](https://github.com/merzlikin-matvey/chess/blob/main/src/move.cpp): representation · Move storage and move arrays · `src/move.cpp`
- [Notation](https://github.com/merzlikin-matvey/chess/blob/main/src/notations.cpp): conversion · Human-readable and protocol move formatting · `src/notations.cpp`
- [Legal moves](https://github.com/merzlikin-matvey/chess/blob/main/src/board/get_legal_moves.cpp): move generation · Legal move generation with check and pin constraints · `src/board/get_legal_moves.cpp`

### Bitboards

Masks, attacks, and magic-bitboard support

- [Masks](https://github.com/merzlikin-matvey/chess/tree/main/include/headers/masks): bitboard masks · Piece and pin masks for attack generation · `include/headers/masks`
- [Bit ops](https://github.com/merzlikin-matvey/chess/blob/main/include/headers/bitboard_operations.hpp): bitboard ops · Shared bitboard utilities and line helpers · `include/headers/bitboard_operations.hpp`
- [Magic tables](https://github.com/merzlikin-matvey/chess/blob/main/include/headers/magic_numbers_constants.hpp): sliding attacks · Magic-bitboard constants and generated attack infrastructure · `include/headers/magic_numbers_constants.hpp`
- [Magic gen](https://github.com/merzlikin-matvey/chess/tree/main/src/magic_numbers_generators): table generation · Generators for bishop, rook, and pin-mask magics · `src/magic_numbers_generators`

### Search

Evaluation, move ordering, and tree search

- [Hashing](https://github.com/merzlikin-matvey/chess/blob/main/src/zobrist.cpp): search state · Zobrist hashing and transposition table caching · `src/zobrist.cpp`
- [AI API](https://github.com/merzlikin-matvey/chess/blob/main/include/headers/ai.hpp): search entry · Public search interface · `include/headers/ai.hpp`
- [Search](https://github.com/merzlikin-matvey/chess/tree/main/src/ai): alpha-beta · Minimax search, quiescence, and move ordering · `src/ai`
- [Eval](https://github.com/merzlikin-matvey/chess/blob/main/src/ai/evaluate_position.cpp): static eval · Position scoring using PSTs and tuning constants · `src/ai/evaluate_position.cpp`

### Interfaces

UCI, examples, and browser-facing entry points

- [UCI](https://github.com/merzlikin-matvey/chess/blob/main/src/uci.cpp): protocol layer · UCI command handling and engine loop · `src/uci.cpp`
- [Examples](https://github.com/merzlikin-matvey/chess/tree/main/example): integration samples · Native, stateless, and WASM demo entry points · `example`

### Validation

Tests and performance harnesses

- [Tests & perf](https://github.com/merzlikin-matvey/chess/tree/main/tests): validation · Legal-move fixtures and perft/search benchmarks · `tests`

## Connections

- chess-lib.hpp → Engine API: re-exports · Umbrella header gathers the public API surface
- Engine API → Board: exposes · Board state is a primary public subsystem
- Engine API → Moves: exposes · Move representations are part of the API
- Engine API → Notation: exposes · Notation helpers are shared across interfaces
- Engine API → AI API: exposes · Search entry points are public
- Board → FEN: uses · Board state is initialized and serialized through FEN
- Board → Moves: updates · Position transitions apply moves
- Board → Legal moves: feeds · Board state drives legality calculation
- Legal moves → Masks: depends on · Legality uses attack and pin masks
- Legal moves → Bit ops: depends on · Bitboard utilities support move generation
- Masks → Magic tables: uses · Sliding attacks rely on precomputed tables
- Magic gen → Magic tables: produces · Generators build or validate magic attack data
- AI API → Search: invokes · Search interface forwards into the search stack
- Search → Eval: scores with · Search uses static evaluation
- Search → Hashing: caches with · Search reuses repeated positions through hashing and TT
- Search → Legal moves: expands · Search explores legal moves from the board layer
- Eval → Board: reads · Evaluation inspects board state
- UCI → Board: drives · UCI commands update positions
- UCI → AI API: queries · UCI requests engine search results
- UCI → Notation: formats · Protocol output uses notation helpers
- Examples → Board: embeds · Examples show direct library use
- Examples → AI API: embeds · Examples may invoke search directly
- Tests & perf → Legal moves: validates · Fixtures and perft exercise move generation
- Tests & perf → Search: benchmarks · Alpha-beta benchmark covers search behavior
