# michaelb7/crafty architecture

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

- Interactive diagram: https://gitdiagram.com/michaelb7/crafty
- Repository: https://github.com/michaelb7/crafty

## Overview

#### Purpose and entry points
Crafty is a native ANSI C chess engine descended from Cray Blitz, built around bitboard position representation and performance-oriented search. The executable lifecycle begins in `src/main.c`, initializes engine-wide state in `src/init.c`, and runs command/game control through `src/crafty.c` and `src/input.c`.

#### Core engine state and position transitions
Shared chess types, board state, and engine declarations are centralized in `src/chess.h`, `src/data.h`, and `src/data.c`. Position setup and legality boundaries are handled by `src/setboard.c` and `src/validate.c`. Search mutates positions through reversible move application in `src/make.c` and `src/unmake.c`; this is the critical state-integrity boundary.

#### Move generation and tactical primitives
Legal candidate generation is provided by `src/movgen.c`, backed by attack/bitboard computations in `src/attacks.c` and static-exchange evaluation in `src/see.c`. These components feed both full search and tactical extensions, while `src/next.c` controls move ordering/selection during node expansion.

#### Search pipeline
Root-level search orchestration is in `src/root.c` and iterative deepening in `src/iterate.c`. The main recursive alpha-beta-style search resides in `src/search.c`, with tactical leaf search in `src/quiesce.c` and pruning/reduction policy in `src/reduce.c`. Time and stop control form a cross-cutting control boundary through `src/time.c` and `src/interrupt.c`.

#### Evaluation, learning, and search memory
Static position scoring is implemented in `src/evaluate.c` with its interface in `src/evaluate.h`. Transposition caching is owned by `src/hash.c`; historical ordering and adaptive information are maintained in `src/history.c` and `src/learn.c`. Search probes can therefore use hash/history data before expanding moves, while evaluation supplies scores at leaves and selected search nodes.

#### External chess knowledge and execution environment
Opening-book support is in `src/book.c`, consuming repository opening data such as `openings/new2500.epd` and `openings/4000_openings_legacy.epd`. Endgame tablebase integration is represented by `src/tbprobe.c`, `src/tbcore.c`, and `src/tbchess.c` (Syzygy-derived code). EPD parsing/testing boundaries are in `src/epd.c` and `src/epdglue.c`.

#### Runtime, concurrency, and builds
The engine is a command-line native program using ANSI C plus limited Unix I/O; platform/build variants are provided by `src/Makefile`, `src/Makefile-official`, and `src/makefile.win`. Parallel search infrastructure is isolated in `src/thread.c`, while user-visible command output and analysis interaction are handled by `src/output.c` and `src/analyze.c`.

Main entry points: [`src/search.c`](https://github.com/michaelb7/crafty/blob/master/src/search.c) (Alpha-beta search), [`src/crafty.c`](https://github.com/michaelb7/crafty/blob/master/src/crafty.c) (Command/game control), [`src/root.c`](https://github.com/michaelb7/crafty/blob/master/src/root.c) (Root & iterative search), [`src/setboard.c`](https://github.com/michaelb7/crafty/blob/master/src/setboard.c) (Position setup & validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Executable entry<br/>ANSI C program<br/>[main.c]"]
  node_init["Engine initialization<br/>startup<br/>[init.c]"]
  node_control["Command/game control<br/>CLI control<br/>[crafty.c]"]
  node_input["Command input<br/>input parser<br/>[input.c]"]
  node_output["Output &amp; analysis<br/>interaction<br/>[output.c]"]
end

subgraph group_position["Position &amp; moves"]
  node_state[("Shared board state<br/>bitboard state<br/>[data.c]")]
  node_setup["Position setup &amp; validation<br/>legality boundary<br/>[setboard.c]"]
  node_movegen["Move generation<br/>candidate generator<br/>[movgen.c]"]
  node_tactics["Attacks &amp; SEE<br/>tactical primitives<br/>[attacks.c]"]
  node_move_state["Make/unmake moves<br/>reversible transition<br/>[make.c]"]
end

subgraph group_search["Search"]
  node_root["Root &amp; iterative search<br/>search orchestration<br/>[root.c]"]
  node_search{{"Alpha-beta search<br/>recursive search<br/>[search.c]"}}
  node_ordering["Move ordering<br/>node selection<br/>[next.c]"]
  node_quiesce["Quiescence &amp; reductions<br/>tactical leaf policy<br/>[quiesce.c]"]
  node_time["Time &amp; interrupt control<br/>search control<br/>[time.c]"]
  node_threads["Parallel search<br/>concurrency<br/>[thread.c]"]
end

subgraph group_knowledge["Knowledge &amp; evaluation"]
  node_evaluation["Static evaluation<br/>position scoring<br/>[evaluate.c]"]
  node_memory[("Hash &amp; learning<br/>search memory<br/>[hash.c]")]
end

subgraph group_external["External chess data"]
  node_book["Opening book<br/>opening knowledge<br/>[book.c]"]
  node_tablebases["Syzygy tablebases<br/>endgame probe<br/>[tbprobe.c]"]
  node_epd["EPD interface<br/>position test parser<br/>[epd.c]"]
end

node_main -->|"starts"| node_init
node_init -->|"initializes"| node_state
node_main -->|"runs"| node_control
node_control -->|"reads commands"| node_input
node_control -->|"sets positions"| node_setup
node_control -->|"requests search"| node_root
node_control -->|"reports"| node_output
node_setup -->|"validates and loads"| node_state
node_root -->|"iterative deepening"| node_search
node_root -.->|"probes opening"| node_book
node_root -->|"sets limits"| node_time
node_search -->|"selects moves"| node_ordering
node_ordering -->|"draws candidates"| node_movegen
node_movegen -->|"uses attacks"| node_tactics
node_search -->|"applies and reverts"| node_move_state
node_move_state -->|"mutates"| node_state
node_search -->|"tactical leaves"| node_quiesce
node_quiesce -->|"scores leaves"| node_evaluation
node_search -->|"evaluates nodes"| node_evaluation
node_search -->|"probes and updates"| node_memory
node_search -.->|"probes endgames"| node_tablebases
node_time -.->|"stops"| node_search
node_threads -.->|"parallelizes"| node_search
node_epd -->|"supplies positions"| node_setup

click node_main "https://github.com/michaelb7/crafty/blob/master/src/main.c"
click node_init "https://github.com/michaelb7/crafty/blob/master/src/init.c"
click node_control "https://github.com/michaelb7/crafty/blob/master/src/crafty.c"
click node_input "https://github.com/michaelb7/crafty/blob/master/src/input.c"
click node_output "https://github.com/michaelb7/crafty/blob/master/src/output.c"
click node_state "https://github.com/michaelb7/crafty/blob/master/src/data.c"
click node_setup "https://github.com/michaelb7/crafty/blob/master/src/setboard.c"
click node_movegen "https://github.com/michaelb7/crafty/blob/master/src/movgen.c"
click node_tactics "https://github.com/michaelb7/crafty/blob/master/src/attacks.c"
click node_move_state "https://github.com/michaelb7/crafty/blob/master/src/make.c"
click node_root "https://github.com/michaelb7/crafty/blob/master/src/root.c"
click node_search "https://github.com/michaelb7/crafty/blob/master/src/search.c"
click node_ordering "https://github.com/michaelb7/crafty/blob/master/src/next.c"
click node_quiesce "https://github.com/michaelb7/crafty/blob/master/src/quiesce.c"
click node_time "https://github.com/michaelb7/crafty/blob/master/src/time.c"
click node_threads "https://github.com/michaelb7/crafty/blob/master/src/thread.c"
click node_evaluation "https://github.com/michaelb7/crafty/blob/master/src/evaluate.c"
click node_memory "https://github.com/michaelb7/crafty/blob/master/src/hash.c"
click node_book "https://github.com/michaelb7/crafty/blob/master/src/book.c"
click node_tablebases "https://github.com/michaelb7/crafty/blob/master/src/tbprobe.c"
click node_epd "https://github.com/michaelb7/crafty/blob/master/src/epd.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_main,node_init,node_control,node_input,node_output toneBlue
class node_state,node_setup,node_movegen,node_tactics,node_move_state toneAmber
class node_root,node_search,node_ordering,node_quiesce,node_time,node_threads toneMint
class node_evaluation,node_memory toneRose
class node_book,node_tablebases,node_epd toneIndigo
```

## Components

### Runtime

- [Executable entry](https://github.com/michaelb7/crafty/blob/master/src/main.c): ANSI C program · `src/main.c`
- [Engine initialization](https://github.com/michaelb7/crafty/blob/master/src/init.c): startup · `src/init.c`
- [Command/game control](https://github.com/michaelb7/crafty/blob/master/src/crafty.c): CLI control · `src/crafty.c`
- [Command input](https://github.com/michaelb7/crafty/blob/master/src/input.c): input parser · `src/input.c`
- [Output & analysis](https://github.com/michaelb7/crafty/blob/master/src/output.c): interaction · `src/output.c`

### Position & moves

- [Shared board state](https://github.com/michaelb7/crafty/blob/master/src/data.c): bitboard state · Shared chess types, board state, and engine declarations. · `src/data.c`
- [Position setup & validation](https://github.com/michaelb7/crafty/blob/master/src/setboard.c): legality boundary · `src/setboard.c`
- [Move generation](https://github.com/michaelb7/crafty/blob/master/src/movgen.c): candidate generator · `src/movgen.c`
- [Attacks & SEE](https://github.com/michaelb7/crafty/blob/master/src/attacks.c): tactical primitives · `src/attacks.c`
- [Make/unmake moves](https://github.com/michaelb7/crafty/blob/master/src/make.c): reversible transition · Critical position state-integrity boundary. · `src/make.c`

### Search

- [Root & iterative search](https://github.com/michaelb7/crafty/blob/master/src/root.c): search orchestration · `src/root.c`
- [Alpha-beta search](https://github.com/michaelb7/crafty/blob/master/src/search.c): recursive search · `src/search.c`
- [Move ordering](https://github.com/michaelb7/crafty/blob/master/src/next.c): node selection · `src/next.c`
- [Quiescence & reductions](https://github.com/michaelb7/crafty/blob/master/src/quiesce.c): tactical leaf policy · `src/quiesce.c`
- [Time & interrupt control](https://github.com/michaelb7/crafty/blob/master/src/time.c): search control · `src/time.c`
- [Parallel search](https://github.com/michaelb7/crafty/blob/master/src/thread.c): concurrency · `src/thread.c`

### Knowledge & evaluation

- [Static evaluation](https://github.com/michaelb7/crafty/blob/master/src/evaluate.c): position scoring · `src/evaluate.c`
- [Hash & learning](https://github.com/michaelb7/crafty/blob/master/src/hash.c): search memory · Transposition cache plus historical and adaptive ordering data. · `src/hash.c`

### External chess data

- [Opening book](https://github.com/michaelb7/crafty/blob/master/src/book.c): opening knowledge · `src/book.c`
- [Syzygy tablebases](https://github.com/michaelb7/crafty/blob/master/src/tbprobe.c): endgame probe · `src/tbprobe.c`
- [EPD interface](https://github.com/michaelb7/crafty/blob/master/src/epd.c): position test parser · `src/epd.c`

## Connections

- Executable entry → Engine initialization: starts
- Engine initialization → Shared board state: initializes
- Executable entry → Command/game control: runs
- Command/game control → Command input: reads commands
- Command/game control → Position setup & validation: sets positions
- Command/game control → Root & iterative search: requests search
- Command/game control → Output & analysis: reports
- Position setup & validation → Shared board state: validates and loads
- Root & iterative search → Alpha-beta search: iterative deepening
- Root & iterative search → Opening book: probes opening
- Root & iterative search → Time & interrupt control: sets limits
- Alpha-beta search → Move ordering: selects moves
- Move ordering → Move generation: draws candidates
- Move generation → Attacks & SEE: uses attacks
- Alpha-beta search → Make/unmake moves: applies and reverts
- Make/unmake moves → Shared board state: mutates
- Alpha-beta search → Quiescence & reductions: tactical leaves
- Quiescence & reductions → Static evaluation: scores leaves
- Alpha-beta search → Static evaluation: evaluates nodes
- Alpha-beta search → Hash & learning: probes and updates
- Alpha-beta search → Syzygy tablebases: probes endgames
- Time & interrupt control → Alpha-beta search: stops
- Parallel search → Alpha-beta search: parallelizes
- EPD interface → Position setup & validation: supplies positions