# thomasahle/sunfish architecture

> Architecture diagram of the GitHub repository thomasahle/sunfish, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomasahle/sunfish
- Repository: https://github.com/thomasahle/sunfish

## Overview

##### Project Type and Purpose
- This is a chess engine project that supports both a command-line (fancy terminal interface) and UCI interface. It has been built for experimentation and minimalism, with optional extensions like NNUE.
- Its design emphasizes a small, highly readable codebase (just 131–2950 lines when built/packed) that is easy to extend (e.g., alternative evaluation functions, different search algorithms).

##### File Structure for Key Components
- Top-Level Modules:
- sunfish.py: The core engine implementation.
- sunfish_nnue.py: Variant that integrates the NNUE models for improved positional evaluation.
- tools/ folder: Contains auxiliary scripts (like fancy.py for terminal UI, uci.py for communicating via UCI protocol, and various test scripts and files).
- nnue/ folder: Houses the pickled neural network models and related test scripts (speed_tests.py, sunfish2.py, sunfish_king.py), indicating an experimental extension to the base engine.
- build/ folder: Contains build and packaging scripts (cleanup, packaging for both standard and NNUE versions) which help in generating a compact executable.
- docs/ folder: Provides documentation and logos useful for branding and perhaps additional diagrammatic references.
- GitHub CI configuration (in .github/workflows) for automated testing/building.

##### Main Components
a. Core Engine Module:
- The chess board representation.
- The Move generation logic.
- The MTD-bi search algorithm (C* implementation).
- Evaluation using static piece-square tables.
b. NNUE Variant Module:
c. Interfaces:
- Command-Line UI: Represent “Tools/Fancy Terminal Interface (tools/fancy.py)” that interacts with the engine.
- UCI Protocol Interface: Represent “UCI Interface (tools/uci.py)” that translates UCI commands.
d. Supporting Infrastructure:
- Build and Packaging: A module labeled “Build Scripts (build/)” showing scripts that clean and pack the engine into a compact executable.
- Testing and Validation: A component for “Test Tools & Test Files (tools/test*.py and tools/test_files)” which verifies engine correctness and performance.
- CI/CD: A small component for “GitHub Actions (.github/workflows/)” that automates testing and build validation.

##### Relationships and Data Flow
- From the engine, show return flows of calculated moves back to the UI.
- For the NNUE variant:
- That build scripts wrap or compile the engine (and its variants) into portable, compressed executables.
- Testing components as verifying interactions and computational correctness. You might illustrate tests as “feedback loops” into the development process.

##### Architectural Patterns and Technologies
- Single-process, monolithic design: The core chess engine is implemented as a single module where gameplay, search, and evaluation all reside together.
- Optional NNUE branch: Illustrate how the modular design allows a different evaluation method (neural network via pickled models) to be plugged into the engine.
- User Command → Input Interface → Engine’s Move Generation → Output Results.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces Layer
    subgraph "Interfaces"
        fancyUI["Tools/Fancy Terminal Interface"]:::interface
        uciUI["UCI Interface"]:::interface
    end

    %% Core Engine
    engine["Sunfish Engine (sunfish.py)"]:::core

    %% Experimental NNUE Module
    subgraph "Experimental NNUE"
        nnue_code["Sunfish NNUE Code (sunfish_nnue.py)"]:::experimental
        nnue_models["NNUE Models (nnue/models)"]:::experimental
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        build_node["Build Scripts (build/)"]:::support
        test_node["Test Suite (tools/tester.py & tools/test_files)"]:::support
        ci_node["CI/CD Pipeline (.github/workflows)"]:::support
    end

    %% Connections from Interfaces to Engine
    fancyUI -->|"Input"| engine
    uciUI   -->|"Input"| engine
    engine   -->|"Results"| fancyUI
    engine   -->|"Results"| uciUI

    %% Connection from Engine to Experimental NNUE
    engine -->|"OptionalNNUEEval"| nnue_code
    nnue_code -->|"loads"| nnue_models

    %% Supporting Infrastructure connections
    build_node -->|"builds"| engine
    test_node  -->|"verifies"| engine
    ci_node    -->|"automates"| test_node

    %% Click Events
    click fancyUI "https://github.com/thomasahle/sunfish/blob/master/tools/fancy.py"
    click uciUI "https://github.com/thomasahle/sunfish/blob/master/tools/uci.py"
    click engine "https://github.com/thomasahle/sunfish/blob/master/sunfish.py"
    click nnue_code "https://github.com/thomasahle/sunfish/blob/master/sunfish_nnue.py"
    click nnue_models "https://github.com/thomasahle/sunfish/tree/master/nnue/models"
    click build_node "https://github.com/thomasahle/sunfish/tree/master/build/"
    click test_node "https://github.com/thomasahle/sunfish/blob/master/tools/tester.py"
    click ci_node "https://github.com/thomasahle/sunfish/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#FFC107,stroke:#E65100,stroke-width:2px;
    classDef interface fill:#8BC34A,stroke:#558B2F,stroke-width:2px;
    classDef experimental fill:#03A9F4,stroke:#0288D1,stroke-width:2px;
    classDef support fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
```
