namebrandon/seajay-chess

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.