# official-pikafish/pikafish architecture

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

- Interactive diagram: https://gitdiagram.com/official-pikafish/pikafish
- Repository: https://github.com/official-pikafish/pikafish

## Overview

Pikafish is a UCI Xiangqi engine: a GUI or other UCI client supplies a position and search command, and the engine returns analysis and a best move. Its runtime spans protocol handling, position and move processing, search, and NNUE evaluation, with thread and transposition-table support. The README documents the UCI product and NNUE network; the source index supports several internal calls, but some protocol and network-loading connections remain unsampled and are therefore shown as unverified.

Main entry points: [`src/search.cpp`](https://github.com/official-pikafish/pikafish/blob/master/src/search.cpp) (Search), [`src/nnue/network.cpp`](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/network.cpp) (NNUE network), [`src/engine.cpp`](https://github.com/official-pikafish/pikafish/blob/master/src/engine.cpp) (Engine control), [`src/position.cpp`](https://github.com/official-pikafish/pikafish/blob/master/src/position.cpp) (Position state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["UCI interface"]
  node_main["Program entry<br/>[main.cpp]"]
  node_uci["UCI protocol<br/>[uci.cpp]"]
  node_engine["Engine control<br/>[engine.cpp]"]
end

subgraph group_xiangqi["Xiangqi model"]
  node_position["Position state<br/>[position.cpp]"]
  node_movegen["Move generation<br/>[movegen.cpp]"]
  node_attacks["Attack tables<br/>[attacks.cpp]"]
  node_bitboard["Bitboard operations<br/>[bitboard.cpp]"]
end

subgraph group_search["Search and evaluation"]
  node_searcher["Search<br/>[search.cpp]"]
  node_evaluation["Position evaluation<br/>[evaluate.cpp]"]
  node_movepick["Move ordering<br/>[movepick.cpp]"]
  node_nnue["NNUE network<br/>[network.cpp]"]
  node_features["NNUE features<br/>[half_ka_v2_hm.cpp]"]
  node_threats["Threat features<br/>[full_threats.cpp]"]
  node_accumulator["NNUE accumulator"]
  node_simd["SIMD kernels<br/>[simd.h]"]
end

subgraph group_runtime["Runtime support"]
  node_threads["Worker threads<br/>[thread.cpp]"]
  node_tt["Transposition table<br/>[tt.cpp]"]
  node_time["Time management<br/>[timeman.cpp]"]
  node_zstd["Zstandard decompression"]
  node_zstdcommon["Zstandard primitives"]
end

node_client(("UCI client / GUI"))

node_client -.->|"sends UCI commands"| node_uci
node_main -->|"starts protocol"| node_uci
node_uci -.->|"dispatches commands"| node_engine
node_engine -->|"sets position"| node_position
node_engine -->|"starts search"| node_searcher
node_engine -->|"loads network"| node_nnue
node_position -->|"uses attacks"| node_attacks
node_position -->|"uses bitboards"| node_bitboard
node_searcher -->|"searches position"| node_position
node_searcher -->|"generates moves"| node_movegen
node_searcher -->|"orders moves"| node_movepick
node_searcher -->|"evaluates positions"| node_evaluation
node_searcher -->|"queries network"| node_nnue
node_searcher -->|"uses accumulator"| node_accumulator
node_searcher -.->|"dispatches work"| node_threads
node_searcher -.->|"probes table"| node_tt
node_searcher -->|"checks limits"| node_time
node_nnue -.->|"uses features"| node_features
node_nnue -.->|"uses accumulator"| node_accumulator
node_features -->|"uses threat features"| node_threats
node_accumulator -->|"uses kernels"| node_simd
node_zstd -->|"uses primitives"| node_zstdcommon
node_nnue -.->|"may decompress weights"| node_zstd

click node_main "https://github.com/official-pikafish/pikafish/blob/master/src/main.cpp"
click node_uci "https://github.com/official-pikafish/pikafish/blob/master/src/uci.cpp"
click node_engine "https://github.com/official-pikafish/pikafish/blob/master/src/engine.cpp"
click node_position "https://github.com/official-pikafish/pikafish/blob/master/src/position.cpp"
click node_movegen "https://github.com/official-pikafish/pikafish/blob/master/src/movegen.cpp"
click node_attacks "https://github.com/official-pikafish/pikafish/blob/master/src/attacks.cpp"
click node_bitboard "https://github.com/official-pikafish/pikafish/blob/master/src/bitboard.cpp"
click node_searcher "https://github.com/official-pikafish/pikafish/blob/master/src/search.cpp"
click node_evaluation "https://github.com/official-pikafish/pikafish/blob/master/src/evaluate.cpp"
click node_movepick "https://github.com/official-pikafish/pikafish/blob/master/src/movepick.cpp"
click node_nnue "https://github.com/official-pikafish/pikafish/blob/master/src/nnue/network.cpp"
click node_features "https://github.com/official-pikafish/pikafish/blob/master/src/nnue/features/half_ka_v2_hm.cpp"
click node_threats "https://github.com/official-pikafish/pikafish/blob/master/src/nnue/features/full_threats.cpp"
click node_accumulator "https://github.com/official-pikafish/pikafish/blob/master/src/nnue/nnue_accumulator.cpp"
click node_simd "https://github.com/official-pikafish/pikafish/blob/master/src/nnue/simd.h"
click node_threads "https://github.com/official-pikafish/pikafish/blob/master/src/thread.cpp"
click node_tt "https://github.com/official-pikafish/pikafish/blob/master/src/tt.cpp"
click node_time "https://github.com/official-pikafish/pikafish/blob/master/src/timeman.cpp"
click node_zstd "https://github.com/official-pikafish/pikafish/tree/master/src/external/decompress"
click node_zstdcommon "https://github.com/official-pikafish/pikafish/tree/master/src/external/common"

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,node_uci,node_engine,node_client toneBlue
class node_position,node_movegen,node_attacks,node_bitboard toneAmber
class node_searcher,node_evaluation,node_movepick,node_nnue,node_features,node_threats,node_accumulator,node_simd toneMint
class node_threads,node_tt,node_time,node_zstd,node_zstdcommon toneRose
```

## Components

### UCI interface

- [Program entry](https://github.com/official-pikafish/pikafish/blob/master/src/main.cpp): `src/main.cpp`
- [UCI protocol](https://github.com/official-pikafish/pikafish/blob/master/src/uci.cpp): `src/uci.cpp`
- [Engine control](https://github.com/official-pikafish/pikafish/blob/master/src/engine.cpp): `src/engine.cpp`

### Xiangqi model

- [Position state](https://github.com/official-pikafish/pikafish/blob/master/src/position.cpp): `src/position.cpp`
- [Move generation](https://github.com/official-pikafish/pikafish/blob/master/src/movegen.cpp): `src/movegen.cpp`
- [Attack tables](https://github.com/official-pikafish/pikafish/blob/master/src/attacks.cpp): `src/attacks.cpp`
- [Bitboard operations](https://github.com/official-pikafish/pikafish/blob/master/src/bitboard.cpp): `src/bitboard.cpp`

### Search and evaluation

- [Search](https://github.com/official-pikafish/pikafish/blob/master/src/search.cpp): `src/search.cpp`
- [Position evaluation](https://github.com/official-pikafish/pikafish/blob/master/src/evaluate.cpp): `src/evaluate.cpp`
- [Move ordering](https://github.com/official-pikafish/pikafish/blob/master/src/movepick.cpp): `src/movepick.cpp`
- [NNUE network](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/network.cpp): `src/nnue/network.cpp`
- [NNUE features](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/features/half_ka_v2_hm.cpp): `src/nnue/features/half_ka_v2_hm.cpp`
- [Threat features](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/features/full_threats.cpp): `src/nnue/features/full_threats.cpp`
- [NNUE accumulator](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/nnue_accumulator.cpp): `src/nnue/nnue_accumulator.cpp`
- [SIMD kernels](https://github.com/official-pikafish/pikafish/blob/master/src/nnue/simd.h): `src/nnue/simd.h`

### Runtime support

- [Worker threads](https://github.com/official-pikafish/pikafish/blob/master/src/thread.cpp): `src/thread.cpp`
- [Transposition table](https://github.com/official-pikafish/pikafish/blob/master/src/tt.cpp): `src/tt.cpp`
- [Time management](https://github.com/official-pikafish/pikafish/blob/master/src/timeman.cpp): `src/timeman.cpp`
- [Zstandard decompression](https://github.com/official-pikafish/pikafish/tree/master/src/external/decompress): `src/external/decompress`
- [Zstandard primitives](https://github.com/official-pikafish/pikafish/tree/master/src/external/common): `src/external/common`

### Other components

- **UCI client / GUI**

## Connections

- UCI client / GUI → UCI protocol: sends UCI commands (evidence: `README.md`)
- Program entry → UCI protocol: starts protocol (evidence: `src/main.cpp`)
- UCI protocol → Engine control: dispatches commands
- Engine control → Position state: sets position (evidence: `src/engine.cpp`)
- Engine control → Search: starts search (evidence: `src/engine.cpp`)
- Engine control → NNUE network: loads network (evidence: `src/engine.cpp`)
- Position state → Attack tables: uses attacks
- Position state → Bitboard operations: uses bitboards
- Search → Position state: searches position (evidence: `src/search.cpp`)
- Search → Move generation: generates moves (evidence: `src/search.cpp`)
- Search → Move ordering: orders moves (evidence: `src/search.cpp`)
- Search → Position evaluation: evaluates positions (evidence: `src/search.cpp`)
- Search → NNUE network: queries network (evidence: `src/search.cpp`)
- Search → NNUE accumulator: uses accumulator (evidence: `src/search.cpp`)
- Search → Worker threads: dispatches work
- Search → Transposition table: probes table
- Search → Time management: checks limits (evidence: `src/search.cpp`)
- NNUE network → NNUE features: uses features
- NNUE network → NNUE accumulator: uses accumulator
- NNUE features → Threat features: uses threat features (evidence: `src/nnue/features/full_threats.cpp`)
- NNUE accumulator → SIMD kernels: uses kernels (evidence: `src/nnue/nnue_accumulator.cpp`)
- Zstandard decompression → Zstandard primitives: uses primitives (evidence: `src/external/decompress/zstd_decompress.cpp`)
- NNUE network → Zstandard decompression: may decompress weights
