# namebrandon/seajay-chess architecture

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

- Interactive diagram: https://gitdiagram.com/namebrandon/seajay-chess
- Repository: https://github.com/namebrandon/seajay-chess

## Overview

1. SeaJay is a single-process C++20 chess engine whose runtime path is: UCI command input, position setup, search, evaluation, and best-move/output reporting. The top-level entry point is `src/main.cpp`, which wires the engine into UCI mode.

2. The codebase is organized into three primary subsystems under `src/`: `core/` for board state and move legality, `evaluation/` for static score computation, and `search/` for deciding moves. `uci/` is the protocol boundary to external GUIs, and `tools/` plus `tests/` provide diagnostics and validation outside the engine loop.

3. `src/core/` is the foundational engine layer. It holds board representation, bitboards, move generation, attack detection, legality/safety checks, static exchange evaluation, perft, and transposition-table primitives. This is the layer that everything else depends on for accurate chess semantics.

4. Move generation is heavily infrastructure-driven: magic bitboards, attack caches, and helper types in `core/types.h` and `core/bitboard.*` support fast legal move production and attack queries. The presence of `attack_cache`, `board_safety`, and `magic_validator` suggests a strong emphasis on correctness and speed for king safety and sliding attacks.

5. `src/evaluation/` computes the static position score used by the search. It is split into material, piece-square tables, pawn structure, and king safety, with an `evaluate.cpp` front end and trace support in `eval_trace.h`. This is a classic handcrafted evaluation pipeline rather than NNUE or external model inference.

6. `src/search/` contains the main decision engine. The visible architecture is iterative deepening negamax with alpha-beta pruning, quiescence search, aspiration windows, move ordering, LMR, null-move pruning, killer/history/countermove heuristics, and singular extension support. Search state is factored into info/context/scratch structs so the engine can carry per-node and per-iteration metadata cleanly.

7. The transposition table sits at the boundary between `core` and `search`: `core/transposition_table.*` provides the shared hash store, while search consumes it for pruning, move ordering, and repetition/history efficiency. There is also an experimental clustered TT implementation under `src/experimental/tt/`, indicating active exploration of alternative TT layouts.

8. `src/uci/` is the external interface layer. It parses UCI commands, manages `uci`/`isready`/`position`/`go`/`stop`, and formats engine info output. `uci_draw_integration.cpp` suggests the engine also has explicit handling for draw claims or draw-related protocol behavior.

9. Time control and search lifecycle are handled inside `search/time_management.*`, `search/search_info.h`, and related iteration data structs. This boundary is important because the search must respond to `stop`, time budgets, and iterative-deepening limits without leaking protocol logic into core search routines.

10. `src/benchmark/` and `src/tools/perft_tool.cpp` are performance-oriented auxiliary entry points. They let the same engine code be exercised outside the normal UCI loop for speed measurements and move-generation validation.

11. `tests/` is broad and architecture-relevant, not just unit coverage. It includes perft suites, regression tests, FEN parsing coverage, SEE tests, transposition-table tests, move-generation utilities, and tactical/EPD position packs. This shows the project treats correctness of chess semantics as a first-class subsystem alongside performance.

12. `tools/` and `docs/project_docs/telemetry/` form an analysis pipeline around engine strength and bug hunting. Scripts collect tactical failures, node explosion data, null-move metrics, and eval harness results; the documentation directories capture investigation reports, tuning plans, and bug audits. In diagram terms, this is an offline feedback loop feeding search/eval refactors and tuning.

13. The build/runtime story is conventional CMake plus Makefile wrappers, with scripts for local builds, OpenBench builds, and a devcontainer for reproducible environments. The README also indicates OpenBench is used for performance validation, so external benchmark infrastructure is part of the development workflow even though it is not part of the engine runtime.

14. `src/experimental/move_picker/` and the many `docs/project_docs/*` refactor plans show the repo has a stable core but active experimentation around move ordering, evaluation refactors, and search API changes. For architecture diagrams, treat these as side branches or feature incubators rather than primary runtime dependencies.

Main entry points: [`src/search/negamax.cpp`](https://github.com/namebrandon/seajay-chess/blob/main/src/search/negamax.cpp) (Negamax), [`src/uci/uci.cpp`](https://github.com/namebrandon/seajay-chess/blob/main/src/uci/uci.cpp) (UCI), [`src/evaluation/evaluate.cpp`](https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/evaluate.cpp) (Eval), [`src/search/search.cpp`](https://github.com/namebrandon/seajay-chess/blob/main/src/search/search.cpp) (Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("main<br/>entrypoint<br/>[main.cpp]"))
end

subgraph group_core["Core"]
  node_board["Board<br/>state<br/>[board.cpp]"]
  node_move_gen["Move gen<br/>generation"]
  node_attack_cache["Attack cache<br/>attack tables<br/>[attack_cache.cpp]"]
  node_safety["Safety<br/>legality<br/>[board_safety.cpp]"]
  node_see["SEE<br/>static exchange<br/>[see.cpp]"]
  node_tt_core[("TT<br/>hash store")]
  node_perft["Perft<br/>validation<br/>[perft.cpp]"]
end

subgraph group_eval["Evaluation"]
  node_evaluate["Eval<br/>scoring front end<br/>[evaluate.cpp]"]
  node_pst["PST<br/>piece-square<br/>[pst.cpp]"]
  node_pawn_structure["Pawns<br/>pawn eval<br/>[pawn_structure.cpp]"]
  node_king_safety["King safety<br/>king eval<br/>[king_safety.cpp]"]
end

subgraph group_search["Search"]
  node_search_main["Search<br/>engine<br/>[search.cpp]"]
  node_negamax["Negamax<br/>alpha-beta<br/>[negamax.cpp]"]
  node_qsearch["Q-search<br/>leaf search<br/>[quiescence.cpp]"]
  node_move_ordering["Order<br/>heuristics<br/>[move_ordering.cpp]"]
  node_time_mgmt["Time<br/>control"]
end

subgraph group_interfaces["Interfaces"]
  node_uci["UCI<br/>protocol<br/>[uci.cpp]"]
  node_info_builder["Info<br/>output formatting<br/>[info_builder.cpp]"]
  node_draw_integration["Draw logic<br/>protocol hook"]
  node_bench(("Bench<br/>[benchmark.cpp]"))
  node_perft_tool(("Perft tool<br/>tooling<br/>[perft_tool.cpp]"))
end

node_main -->|"starts"| node_uci
node_uci -->|"position"| node_board
node_uci -->|"go"| node_search_main
node_uci -->|"stop/time"| node_time_mgmt
node_uci -->|"info"| node_info_builder
node_uci -->|"draw"| node_draw_integration
node_search_main -->|"iterates"| node_negamax
node_search_main -->|"limits"| node_time_mgmt
node_search_main -->|"hash"| node_tt_core
node_negamax -->|"leafs"| node_qsearch
node_negamax -->|"orders"| node_move_ordering
node_negamax -->|"scores"| node_evaluate
node_negamax -->|"prunes"| node_tt_core
node_negamax -->|"explores"| node_board
node_qsearch -->|"filters"| node_see
node_qsearch -->|"leaf eval"| node_evaluate
node_board -->|"generates"| node_move_gen
node_move_gen -->|"queries"| node_attack_cache
node_move_gen -->|"checks"| node_safety
node_safety -->|"attacks"| node_attack_cache
node_evaluate -->|"uses"| node_pst
node_evaluate -->|"uses"| node_pawn_structure
node_evaluate -->|"uses"| node_king_safety
node_perft -->|"tests"| node_board
node_perft_tool -->|"runs"| node_perft
node_bench -->|"measures"| node_search_main
node_bench -->|"measures"| node_evaluate

click node_main "https://github.com/namebrandon/seajay-chess/blob/main/src/main.cpp"
click node_uci "https://github.com/namebrandon/seajay-chess/blob/main/src/uci/uci.cpp"
click node_info_builder "https://github.com/namebrandon/seajay-chess/blob/main/src/uci/info_builder.cpp"
click node_draw_integration "https://github.com/namebrandon/seajay-chess/blob/main/src/uci/uci_draw_integration.cpp"
click node_board "https://github.com/namebrandon/seajay-chess/blob/main/src/core/board.cpp"
click node_move_gen "https://github.com/namebrandon/seajay-chess/blob/main/src/core/move_generation.cpp"
click node_attack_cache "https://github.com/namebrandon/seajay-chess/blob/main/src/core/attack_cache.cpp"
click node_safety "https://github.com/namebrandon/seajay-chess/blob/main/src/core/board_safety.cpp"
click node_see "https://github.com/namebrandon/seajay-chess/blob/main/src/core/see.cpp"
click node_tt_core "https://github.com/namebrandon/seajay-chess/blob/main/src/core/transposition_table.cpp"
click node_perft "https://github.com/namebrandon/seajay-chess/blob/main/src/core/perft.cpp"
click node_evaluate "https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/evaluate.cpp"
click node_pst "https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/pst.cpp"
click node_pawn_structure "https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/pawn_structure.cpp"
click node_king_safety "https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/king_safety.cpp"
click node_search_main "https://github.com/namebrandon/seajay-chess/blob/main/src/search/search.cpp"
click node_negamax "https://github.com/namebrandon/seajay-chess/blob/main/src/search/negamax.cpp"
click node_qsearch "https://github.com/namebrandon/seajay-chess/blob/main/src/search/quiescence.cpp"
click node_move_ordering "https://github.com/namebrandon/seajay-chess/blob/main/src/search/move_ordering.cpp"
click node_time_mgmt "https://github.com/namebrandon/seajay-chess/blob/main/src/search/time_management.cpp"
click node_bench "https://github.com/namebrandon/seajay-chess/blob/main/src/benchmark/benchmark.cpp"
click node_perft_tool "https://github.com/namebrandon/seajay-chess/blob/main/src/tools/perft_tool.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 toneBlue
class node_board,node_move_gen,node_attack_cache,node_safety,node_see,node_tt_core,node_perft toneAmber
class node_evaluate,node_pst,node_pawn_structure,node_king_safety toneMint
class node_search_main,node_negamax,node_qsearch,node_move_ordering,node_time_mgmt toneRose
class node_uci,node_info_builder,node_draw_integration,node_bench,node_perft_tool toneIndigo
```

## Components

### Runtime

Engine entrypoints and protocol flow

- [main](https://github.com/namebrandon/seajay-chess/blob/main/src/main.cpp): entrypoint · Starts the engine and wires UCI mode · `src/main.cpp`

### Core

Board state, legality, and shared chess primitives

- [Board](https://github.com/namebrandon/seajay-chess/blob/main/src/core/board.cpp): state · Position representation and move application · `src/core/board.cpp`
- [Move gen](https://github.com/namebrandon/seajay-chess/blob/main/src/core/move_generation.cpp): generation · Produces legal and pseudo-legal moves · `src/core/move_generation.cpp`
- [Attack cache](https://github.com/namebrandon/seajay-chess/blob/main/src/core/attack_cache.cpp): attack tables · Fast attack lookup support · `src/core/attack_cache.cpp`
- [Safety](https://github.com/namebrandon/seajay-chess/blob/main/src/core/board_safety.cpp): legality · King safety and legality checks · `src/core/board_safety.cpp`
- [SEE](https://github.com/namebrandon/seajay-chess/blob/main/src/core/see.cpp): static exchange · Captures exchange evaluation for move filtering · `src/core/see.cpp`
- [TT](https://github.com/namebrandon/seajay-chess/blob/main/src/core/transposition_table.cpp): hash store · Shared transposition table implementation · `src/core/transposition_table.cpp`
- [Perft](https://github.com/namebrandon/seajay-chess/blob/main/src/core/perft.cpp): validation · Move-generation validation and counting · `src/core/perft.cpp`

### Evaluation

Static scoring pipeline

- [Eval](https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/evaluate.cpp): scoring front end · Computes static position score · `src/evaluation/evaluate.cpp`
- [PST](https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/pst.cpp): piece-square · Piece-square and positional tables · `src/evaluation/pst.cpp`
- [Pawns](https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/pawn_structure.cpp): pawn eval · Pawn structure features and scoring · `src/evaluation/pawn_structure.cpp`
- [King safety](https://github.com/namebrandon/seajay-chess/blob/main/src/evaluation/king_safety.cpp): king eval · King safety terms for evaluation · `src/evaluation/king_safety.cpp`

### Search

Move selection and tree exploration

- [Search](https://github.com/namebrandon/seajay-chess/blob/main/src/search/search.cpp): engine · Iterative deepening search driver · `src/search/search.cpp`
- [Negamax](https://github.com/namebrandon/seajay-chess/blob/main/src/search/negamax.cpp): alpha-beta · Main tree search with pruning · `src/search/negamax.cpp`
- [Q-search](https://github.com/namebrandon/seajay-chess/blob/main/src/search/quiescence.cpp): leaf search · Quiescence search for tactical stability · `src/search/quiescence.cpp`
- [Order](https://github.com/namebrandon/seajay-chess/blob/main/src/search/move_ordering.cpp): heuristics · Ranks moves using heuristics and history · `src/search/move_ordering.cpp`
- [Time](https://github.com/namebrandon/seajay-chess/blob/main/src/search/time_management.cpp): control · Time budgets and stop handling · `src/search/time_management.cpp`

### Interfaces

UCI, benchmarking, and external tooling

- [UCI](https://github.com/namebrandon/seajay-chess/blob/main/src/uci/uci.cpp): protocol · Parses commands and produces engine responses · `src/uci/uci.cpp`
- [Info](https://github.com/namebrandon/seajay-chess/blob/main/src/uci/info_builder.cpp): output formatting · Builds UCI info strings and reporting payloads · `src/uci/info_builder.cpp`
- [Draw logic](https://github.com/namebrandon/seajay-chess/blob/main/src/uci/uci_draw_integration.cpp): protocol hook · Handles draw-related UCI behavior · `src/uci/uci_draw_integration.cpp`
- [Bench](https://github.com/namebrandon/seajay-chess/blob/main/src/benchmark/benchmark.cpp): benchmark · Non-UCI performance entrypoint · `src/benchmark/benchmark.cpp`
- [Perft tool](https://github.com/namebrandon/seajay-chess/blob/main/src/tools/perft_tool.cpp): tooling · Standalone perft runner · `src/tools/perft_tool.cpp`

## Connections

- main → UCI: starts · Main wires the engine into UCI mode
- UCI → Board: position · Protocol commands build or update positions
- UCI → Search: go · Search is launched from UCI requests
- UCI → Time: stop/time · Protocol lifecycle feeds search control
- UCI → Info: info · Formats engine output for the GUI
- UCI → Draw logic: draw · Handles draw-related protocol paths
- Search → Negamax: iterates · Driver coordinates deepening and principal search
- Search → Time: limits · Search obeys time and stop constraints
- Search → TT: hash · Search consults transposition table data
- Negamax → Q-search: leafs · Main search falls through to quiescence
- Negamax → Order: orders · Heuristics rank candidate moves
- Negamax → Eval: scores · Static evaluation anchors tree decisions
- Negamax → TT: prunes · Hash entries support cutoffs and ordering
- Negamax → Board: explores · Search advances and undoes positions
- Q-search → SEE: filters · SEE helps manage tactical capture search
- Q-search → Eval: leaf eval · Static score is used at quiescent leaves
- Board → Move gen: generates · Board state drives legal move production
- Move gen → Attack cache: queries · Fast attack tables support generation
- Move gen → Safety: checks · Legality depends on king safety logic
- Safety → Attack cache: attacks · Safety uses attack queries for checks and evasion
- Eval → PST: uses · Positional scoring includes piece-square terms
- Eval → Pawns: uses · Pawn structure contributes to static score
- Eval → King safety: uses · King safety terms feed evaluation
- Perft → Board: tests · Perft counts rely on accurate board semantics
- Perft tool → Perft: runs · Standalone tool exercises perft logic
- Bench → Search: measures · Benchmark entrypoint stresses search performance
- Bench → Eval: measures · Benchmarks can isolate evaluation cost