# balakumaran-ks/chess-engine architecture

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

- Interactive diagram: https://gitdiagram.com/balakumaran-ks/chess-engine
- Repository: https://github.com/balakumaran-ks/chess-engine

## Overview

1. **What this repository is**
   - A pure Java chess engine built around **bitboards**, packaged under the `engine.*` namespace.
   - Its core runtime pipeline is: **FEN/position input -> Board state -> legal move generation -> search -> evaluation -> best move output**.
   - The README also describes a **UCI command loop** as the integration boundary for chess GUIs, though the main source tree shown is dominated by engine internals.

2. **Primary architectural boundary**
   - The engine is split into a few clean layers:
     - **constants**: chess domain enums and square mapping
     - **board**: position state and FEN parsing
     - **move**: attack lookup and legal move generation
     - **evaluation**: static scoring
     - **search**: game-tree search, ordering, and caching
     - **utils**: shared bitboard helpers
   - This is a mostly in-process engine; there is no HTTP/service layer in the tree.

3. **Chess domain model**
   - `engine.constants` defines the fundamental coordinate and piece model: `Square`, `Piece`, `Color`, `File`, `Rank`.
   - These types anchor the bitboard representation and keep the rest of the engine from using raw indices everywhere.
   - `SquareUtils` provides conversions and bitboard-oriented helpers used across board, move generation, and tests.

4. **Board state and position lifecycle**
   - `engine.board.Board` is the central state object.
   - The board is represented as **12 piece bitboards** plus occupancy/game-state metadata, which supports fast bitwise operations and search-friendly updates.
   - `FenParser` handles position initialization and round-tripping from FEN.
   - `UndoInfo` supports **make/unmake** move execution via a state stack, which is crucial for deep search without copying boards every ply.

5. **Move generation subsystem**
   - `engine.move` is responsible for generating candidate moves and filtering them into legal moves.
   - It uses **precomputed attack tables** for king/knight/pawn moves and **magic bitboards** for sliding-piece attacks.
   - Key classes here are `AttackTables`, `MagicBitboards`, `MoveGenerator`, `Move`, `MoveList`, and `MoveFlag`.
   - The design separates attack lookup, move representation, and move collection so the generator can be reused by perft, search, and tests.

6. **Search subsystem**
   - `engine.search.Searcher` is the main decision-making component.
   - The README describes a search stack of **negamax alpha-beta**, **iterative deepening**, and **quiescence search**.
   - `SearchLimits` defines the search boundary; `Bound` and `MoveOrdering` support pruning and ordering.
   - This subsystem is the bridge between “generate legal moves” and “choose one best move.”

7. **Caching and board hashing**
   - `Zobrist` provides position hashing for transposition-table keys.
   - `TranspositionTable` and `TranspositionTableEntry` cache previously analyzed positions to avoid redundant search.
   - This is a major performance boundary: the searcher consults the table to reuse prior results and improve move ordering.
   - The presence of `Bound` suggests standard alpha-beta score semantics are preserved in the cache.

8. **Move ordering as a search accelerator**
   - `MoveOrdering` is a dedicated search helper, not part of raw move generation.
   - That separation matters architecturally: generation produces legal candidates, while ordering decides which candidates to search first to maximize pruning.
   - The README indicates common heuristics such as MVV-LVA, killer moves, and history-like ordering are used.

9. **Evaluation subsystem**
   - `engine.evaluation.Evaluator` scores positions statically when search reaches leaf nodes or quiescence boundaries.
   - `PieceSquareTables` provides positional tuning on top of material values.
   - The README describes the evaluation as a combination of **material, tapered piece-square tables, mobility, and king safety**.
   - This subsystem is intentionally isolated so search can treat evaluation as a black-box score function.

10. **Data flow through a typical engine turn**
    - A position enters as FEN or a UCI `position` command.
    - `Board` materializes the state.
    - `MoveGenerator` enumerates legal moves.
    - `Searcher` explores the game tree, repeatedly calling generation, make/unmake, and evaluation.
    - The result is a single move emitted back out through UCI in coordinate notation.

11. **Testing and correctness strategy**
    - The test tree mirrors the engine layers: board, constants, move, evaluation, search, and utils.
    - `perft`-style validation is central to correctness for move generation and board execution.
    - Tests such as `ZobristTest`, `TranspositionTableTest`, and `MoveExecutionTest` indicate the engine is validating not just functionality, but also the integrity of search-supporting infrastructure.
    - This is important because chess engines can be “functionally close” while still being wrong at deep search depths.

12. **Tooling and automation**
    - The project is built with **Maven** and has GitHub Actions workflows for **CI** and **performance testing**.
    - That implies the repository treats performance regressions as a first-class concern, which is typical for chess engines where small changes can affect strength.
    - Documentation is extensive and part of the architecture: `docs/BOARD_DESIGN.md`, `docs/MOVE_GENERATION.md`, `docs/SEARCH.md`, and `docs/UCI_PROTOCOL.md` describe the major subsystems.

13. **Optional persistence boundary**
    - The README mentions a repository abstraction for position storage, including an in-memory default and a MongoDB-backed option documented in `docs/DATABASE_INTEGRATION.md`.
    - That appears to be an **optional analysis/persistence extension**, not part of the core search path.
    - In an architecture diagram, it should be shown as a sidecar or external integration, not as a dependency required for engine operation.

14. **Overall shape**
    - This is a **single-process chess engine core** with strong separation between:
      - domain model,
      - board state management,
      - move generation,
      - search,
      - evaluation,
      - and external protocol integration.
    - The most important runtime dependency chain is **Board -> MoveGenerator -> Searcher -> Evaluator**, with **Zobrist/TranspositionTable** feeding search efficiency and **UCI** serving as the outer interface.

Main entry points: [`src/main/java/engine/board/Board.java`](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/Board.java) (Board), [`src/main/java/engine/search/Searcher.java`](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Searcher.java) (Searcher), [`src/main/java/engine/move/MoveGenerator.java`](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MoveGenerator.java) (Move generator), [`src/main/java/engine/search/TranspositionTable.java`](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/TranspositionTable.java) (Transposition table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Engine Core"]
  node_color(("Color<br/>domain enum<br/>[Color.java]"))
  node_piece(("Piece<br/>domain enum<br/>[Piece.java]"))
  node_square(("Square<br/>domain enum<br/>[Square.java]"))
  node_square_utils["Square utils<br/>coord helpers<br/>[SquareUtils.java]"]
  node_board["Board<br/>position state<br/>[Board.java]"]
  node_fen["FEN parser<br/>position I/O<br/>[FenParser.java]"]
  node_undo["Undo info<br/>state stack<br/>[UndoInfo.java]"]
  node_attack_tables["Attack tables<br/>lookup tables<br/>[AttackTables.java]"]
  node_magic["Magic bitboards<br/>sliding attacks"]
  node_movegen["Move generator<br/>legal moves<br/>[MoveGenerator.java]"]
  node_movelist["Move list<br/>move container<br/>[MoveList.java]"]
  node_move["Move<br/>[Move.java]"]
  node_evaluator["Evaluator<br/>static scoring<br/>[Evaluator.java]"]
  node_pst["Piece-square tables<br/>evaluation tables"]
end

subgraph group_search["Search Stack"]
  node_searcher["Searcher<br/>alpha-beta search<br/>[Searcher.java]"]
  node_ordering["Move ordering<br/>search heuristic<br/>[MoveOrdering.java]"]
  node_tt[("Transposition table<br/>search cache")]
  node_zobrist["Zobrist<br/>position hashing<br/>[Zobrist.java]"]
  node_limits["Search limits<br/>search bounds<br/>[SearchLimits.java]"]
  node_bound(("Bound<br/>score semantics<br/>[Bound.java]"))
end

subgraph group_tests["Tests"]
  node_board_test["Board tests<br/>verification<br/>[BoardTest.java]"]
  node_move_test["Move tests<br/>verification"]
  node_search_test["Search tests<br/>verification<br/>[SearcherTest.java]"]
  node_eval_test["Eval tests<br/>verification<br/>[EvaluatorTest.java]"]
end

subgraph group_integration["Integration"]
  node_uci["UCI loop<br/>protocol boundary"]
  node_repo_store[("Position store<br/>optional persistence")]
end

node_uci -->|"position input"| node_board
node_board -->|"load/save"| node_fen
node_board -->|"make/unmake"| node_undo
node_square -->|"coords"| node_square_utils
node_piece -->|"pieces"| node_board
node_color -->|"side"| node_board
node_board -->|"occupancy"| node_attack_tables
node_board -->|"sliders"| node_magic
node_attack_tables -->|"lookup"| node_movegen
node_magic -->|"lookup"| node_movegen
node_movegen -->|"collect"| node_movelist
node_movegen -->|"emit"| node_move
node_movegen -->|"legal moves"| node_searcher
node_searcher -->|"prioritize"| node_ordering
node_ordering -->|"history"| node_tt
node_searcher -->|"probe/store"| node_tt
node_zobrist -->|"keys"| node_tt
node_searcher -->|"constraints"| node_limits
node_searcher -->|"scores"| node_bound
node_searcher -->|"leaf eval"| node_evaluator
node_evaluator -->|"tables"| node_pst
node_repo_store -.->|"optional state"| node_board
node_board_test -->|"verifies"| node_board
node_move_test -->|"verifies"| node_movegen
node_search_test -->|"verifies"| node_searcher
node_search_test -->|"verifies"| node_tt
node_search_test -->|"verifies"| node_zobrist
node_eval_test -->|"verifies"| node_evaluator

click node_repo_store "https://github.com/balakumaran-ks/chess-engine/blob/main/docs/DATABASE_INTEGRATION.md"
click node_color "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Color.java"
click node_piece "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Piece.java"
click node_square "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Square.java"
click node_square_utils "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/utils/SquareUtils.java"
click node_board "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/Board.java"
click node_fen "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/FenParser.java"
click node_undo "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/UndoInfo.java"
click node_attack_tables "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/AttackTables.java"
click node_magic "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MagicBitboards.java"
click node_movegen "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MoveGenerator.java"
click node_movelist "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MoveList.java"
click node_move "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/Move.java"
click node_evaluator "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/evaluation/Evaluator.java"
click node_pst "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/evaluation/PieceSquareTables.java"
click node_searcher "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Searcher.java"
click node_ordering "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/MoveOrdering.java"
click node_tt "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/TranspositionTable.java"
click node_zobrist "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Zobrist.java"
click node_limits "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/SearchLimits.java"
click node_bound "https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Bound.java"
click node_board_test "https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/board/BoardTest.java"
click node_move_test "https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/move/MoveExecutionTest.java"
click node_search_test "https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/search/SearcherTest.java"
click node_eval_test "https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/evaluation/EvaluatorTest.java"

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_color,node_piece,node_square,node_square_utils,node_board,node_fen,node_undo,node_attack_tables,node_magic,node_movegen,node_movelist,node_move,node_evaluator,node_pst toneBlue
class node_searcher,node_ordering,node_tt,node_zobrist,node_limits,node_bound toneAmber
class node_board_test,node_move_test,node_search_test,node_eval_test toneMint
class node_uci,node_repo_store toneRose
```

## Components

### Engine Core

Main in-process chess engine layers.

- [Color](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Color.java): domain enum · Side-to-move model for the chess domain. · `src/main/java/engine/constants/Color.java`
- [Piece](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Piece.java): domain enum · Piece identity and related domain constants. · `src/main/java/engine/constants/Piece.java`
- [Square](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/constants/Square.java): domain enum · Board coordinate system and indexed squares. · `src/main/java/engine/constants/Square.java`
- [Square utils](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/utils/SquareUtils.java): coord helpers · Conversions and bitboard-oriented square helpers. · `src/main/java/engine/utils/SquareUtils.java`
- [Board](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/Board.java): position state · Central bitboard-based position state and move execution boundary. · `src/main/java/engine/board/Board.java`
- [FEN parser](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/FenParser.java): position I/O · Initializes and serializes positions from FEN. · `src/main/java/engine/board/FenParser.java`
- [Undo info](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/board/UndoInfo.java): state stack · Supports make/unmake move search without copying boards. · `src/main/java/engine/board/UndoInfo.java`
- [Attack tables](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/AttackTables.java): lookup tables · Precomputed king, knight, and pawn attack generation helpers. · `src/main/java/engine/move/AttackTables.java`
- [Magic bitboards](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MagicBitboards.java): sliding attacks · Fast rook and bishop attack lookup via magic bitboards. · `src/main/java/engine/move/MagicBitboards.java`
- [Move generator](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MoveGenerator.java): legal moves · Generates and filters legal chess moves. · `src/main/java/engine/move/MoveGenerator.java`
- [Move list](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/MoveList.java): move container · Collects candidate and legal moves for search and validation. · `src/main/java/engine/move/MoveList.java`
- [Move](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/move/Move.java): move record · Compact move representation used across generation and search. · `src/main/java/engine/move/Move.java`
- [Evaluator](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/evaluation/Evaluator.java): static scoring · Evaluates leaf positions using material and positional heuristics. · `src/main/java/engine/evaluation/Evaluator.java`
- [Piece-square tables](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/evaluation/PieceSquareTables.java): evaluation tables · Positional tuning tables for pieces and phases. · `src/main/java/engine/evaluation/PieceSquareTables.java`

### Search Stack

Decision-making, ordering, and caching.

- [Searcher](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Searcher.java): alpha-beta search · Main negamax search with iterative deepening and quiescence. · `src/main/java/engine/search/Searcher.java`
- [Move ordering](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/MoveOrdering.java): search heuristic · Ranks moves to maximize pruning efficiency. · `src/main/java/engine/search/MoveOrdering.java`
- [Transposition table](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/TranspositionTable.java): search cache · Caches analyzed positions to avoid redundant search. · `src/main/java/engine/search/TranspositionTable.java`
- [Zobrist](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Zobrist.java): position hashing · Hashes positions for transposition-table keys. · `src/main/java/engine/search/Zobrist.java`
- [Search limits](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/SearchLimits.java): search bounds · Depth, time, and constraint settings for a search. · `src/main/java/engine/search/SearchLimits.java`
- [Bound](https://github.com/balakumaran-ks/chess-engine/blob/main/src/main/java/engine/search/Bound.java): score semantics · Represents alpha-beta and transposition-table bound types. · `src/main/java/engine/search/Bound.java`

### Tests

Representative validation coverage by subsystem.

- [Board tests](https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/board/BoardTest.java): verification · Board state and move execution correctness tests. · `src/test/java/engine/board/BoardTest.java`
- [Move tests](https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/move/MoveExecutionTest.java): verification · Attack tables and move execution validation. · `src/test/java/engine/move/MoveExecutionTest.java`
- [Search tests](https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/search/SearcherTest.java): verification · Searcher, ordering, transposition table, and hashing tests. · `src/test/java/engine/search/SearcherTest.java`
- [Eval tests](https://github.com/balakumaran-ks/chess-engine/blob/main/src/test/java/engine/evaluation/EvaluatorTest.java): verification · Evaluator correctness tests. · `src/test/java/engine/evaluation/EvaluatorTest.java`

### Integration

External protocol and optional storage boundary.

- **UCI loop**: protocol boundary · External command loop for chess GUIs and engine I/O.
- [Position store](https://github.com/balakumaran-ks/chess-engine/blob/main/docs/DATABASE_INTEGRATION.md): optional persistence · Repository-backed position persistence, including in-memory and database variants. · `docs/DATABASE_INTEGRATION.md`

## Connections

- UCI loop → Board: position input · UCI position commands materialize into board state.
- Board → FEN parser: load/save · Board state is initialized from and round-tripped through FEN.
- Board → Undo info: make/unmake · Search uses undo info to apply and revert moves efficiently.
- Square → Square utils: coords · Square utilities operate on the coordinate model.
- Piece → Board: pieces · Piece identity feeds the bitboard board representation.
- Color → Board: side · Side-to-move metadata is part of board state.
- Board → Attack tables: occupancy · Board occupancy feeds precomputed attack lookup.
- Board → Magic bitboards: sliders · Sliding-piece attacks depend on current occupancy.
- Attack tables → Move generator: lookup · Non-sliding attacks are used during move generation.
- Magic bitboards → Move generator: lookup · Sliding attacks are used during move generation.
- Move generator → Move list: collect · Generated moves are accumulated in a move list.
- Move generator → Move: emit · Move generation produces move records.
- Move generator → Searcher: legal moves · Search consumes legal moves from the generator.
- Searcher → Move ordering: prioritize · Searcher relies on move ordering before expanding nodes.
- Move ordering → Transposition table: history · Ordering consults cached search results and move history signals.
- Searcher → Transposition table: probe/store · Search probes and updates the transposition table.
- Zobrist → Transposition table: keys · Zobrist hashes provide transposition-table keys.
- Searcher → Search limits: constraints · Search limits bound iterative deepening and time usage.
- Searcher → Bound: scores · Searcher interprets alpha-beta score bounds.
- Searcher → Evaluator: leaf eval · Searcher calls evaluator at leaf and quiescence boundaries.
- Evaluator → Piece-square tables: tables · Evaluator uses piece-square tables for positional scoring.
- Position store → Board: optional state · Optional persistence can materialize or archive positions.
- Board tests → Board: verifies · Tests board state and move execution behavior.
- Move tests → Move generator: verifies · Tests validate move generation and execution rules.
- Search tests → Searcher: verifies · Tests validate search behavior and support infrastructure.
- Search tests → Transposition table: verifies · Tests validate transposition-table behavior.
- Search tests → Zobrist: verifies · Tests validate position hashing stability.
- Eval tests → Evaluator: verifies · Tests validate static scoring behavior.