# pauljoohyunkim/simple-chess-engine architecture

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

- Interactive diagram: https://gitdiagram.com/pauljoohyunkim/simple-chess-engine
- Repository: https://github.com/pauljoohyunkim/simple-chess-engine

## Overview

Simple Chess Engine is a C chess engine exposed as both an interactive playable program and a UCI engine. The main workflow accepts a position and search request, maintains chess state, searches candidate moves, evaluates positions, and returns a best move. Its documented capabilities include bitboards, magic-bitboard move generation, alpha-beta with quiescence and iterative deepening, interchangeable SEF/HCEF evaluation, and UCI helper-thread search. Relationships involving unsampled search and playable-CLI code are omitted or marked unverified.

Main entry points: [`src/engine.c`](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/engine.c) (Search And Tables), [`src/bin/sce_play.c`](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/bin/sce_play.c) (Playable CLI), [`src/uci.c`](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/uci.c) (UCI Protocol), [`src/chess.c`](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/chess.c) (Board And Moves)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_play_cli["Playable CLI<br/>[sce_play.c]"]
  node_uci_app["UCI Engine App<br/>[sce_uci_engine.c]"]
  node_uci["UCI Protocol<br/>[uci.c]"]
end

subgraph group_chess["Chess State"]
  node_fen["FEN Positions<br/>[fen.c]"]
  node_chess_state["Board And Moves<br/>[chess.c]"]
  node_magic["Magic Bitboards<br/>[magic.c]"]
end

subgraph group_search["Search Engine"]
  node_engine["Search And Tables<br/>[engine.c]"]
end

subgraph group_evaluation["Position Evaluation"]
  node_sef["Simplified Eval<br/>[sef.c]"]
  node_hcef["Handcrafted Eval<br/>[hcef.c]"]
  node_pst["Piece Tables<br/>[pst.c]"]
end

node_player(("Player"))
node_uci_host(("UCI Host"))

node_player -.->|"plays through"| node_play_cli
node_uci_host -.->|"starts"| node_uci_app
node_uci_app -->|"dispatches commands"| node_uci
node_uci_app -->|"initializes search"| node_engine
node_uci -->|"loads positions"| node_fen
node_uci -->|"applies moves"| node_chess_state
node_uci -.->|"requests search"| node_engine
node_engine -->|"generates moves"| node_chess_state
node_engine -.->|"uses eval callback"| node_sef
node_engine -.->|"uses eval callback"| node_hcef
node_hcef -->|"uses piece tables"| node_pst
node_chess_state -->|"uses slider tables"| node_magic
node_play_cli -.->|"plays moves"| node_chess_state
node_play_cli -.->|"requests best move"| node_engine
node_play_cli -.->|"selects evaluation"| node_hcef

click node_play_cli "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/bin/sce_play.c"
click node_uci_app "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/bin/sce_uci_engine.c"
click node_uci "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/uci.c"
click node_fen "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/fen.c"
click node_chess_state "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/chess.c"
click node_magic "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/magic.c"
click node_engine "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/engine.c"
click node_sef "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/sef.c"
click node_hcef "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/hcef.c"
click node_pst "https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/pst.c"

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_play_cli,node_uci_app,node_uci toneBlue
class node_fen,node_chess_state,node_magic toneAmber
class node_engine toneMint
class node_sef,node_hcef,node_pst toneRose
class node_player,node_uci_host toneIndigo
```

## Components

### User Interfaces

- [Playable CLI](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/bin/sce_play.c): `src/bin/sce_play.c`
- [UCI Engine App](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/bin/sce_uci_engine.c): `src/bin/sce_uci_engine.c`
- [UCI Protocol](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/uci.c): `src/uci.c`

### Chess State

- [FEN Positions](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/fen.c): `src/fen.c`
- [Board And Moves](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/chess.c): `src/chess.c`
- [Magic Bitboards](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/magic.c): `src/magic.c`

### Search Engine

- [Search And Tables](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/engine.c): `src/engine.c`

### Position Evaluation

- [Simplified Eval](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/sef.c): `src/eval/sef.c`
- [Handcrafted Eval](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/hcef.c): `src/eval/hcef.c`
- [Piece Tables](https://github.com/pauljoohyunkim/simple-chess-engine/blob/main/src/eval/pst.c): `src/eval/pst.c`

### Other components

- **Player**
- **UCI Host**

## Connections

- Player → Playable CLI: plays through
- UCI Host → UCI Engine App: starts
- UCI Engine App → UCI Protocol: dispatches commands (evidence: `src/bin/sce_uci_engine.c`)
- UCI Engine App → Search And Tables: initializes search (evidence: `src/bin/sce_uci_engine.c`)
- UCI Protocol → FEN Positions: loads positions (evidence: `src/uci.c`)
- UCI Protocol → Board And Moves: applies moves (evidence: `src/uci.c`)
- UCI Protocol → Search And Tables: requests search
- Search And Tables → Board And Moves: generates moves (evidence: `src/engine.c`)
- Search And Tables → Simplified Eval: uses eval callback
- Search And Tables → Handcrafted Eval: uses eval callback
- Handcrafted Eval → Piece Tables: uses piece tables (evidence: `src/eval/hcef.c`)
- Board And Moves → Magic Bitboards: uses slider tables (evidence: `src/chess.c`)
- Playable CLI → Board And Moves: plays moves
- Playable CLI → Search And Tables: requests best move
- Playable CLI → Handcrafted Eval: selects evaluation
