balakumaran-ks/chess-engine

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.