# xu-shawn/serendipity architecture

> Architecture diagram of the GitHub repository xu-shawn/serendipity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xu-shawn/serendipity
- Repository: https://github.com/xu-shawn/serendipity

## Overview

##### Main Components Overview

a. Core Engine Components:
- Search System
- Evaluation System (NNUE)
- UCI Interface
- Move Generation (via chesslib)

##### Detailed Component Breakdown

A. Search System (Primary Component):
- Alpha-Beta Search
- Move Ordering System
- Transposition Table
- History Tables
- Thread Management
- Time Management

B. Neural Network Evaluation (NNUE):
- Adjacent to the Search System
- Include:
- Accumulator Stack
- SIMD/Scalar Inference options
- Network Architecture

C. UCI Interface:
- At the top level as the external interface
- Connections to:
- Command Processing
- Search Control
- Configuration Options

##### Specific Implementation Details

A. Search System Details:
**┌─ Search System ─────────────────┐**
- Iterative Deepening          │
- PVS                          │
- Move Ordering                │
- Pruning & Extensions         │
- Multi-threading (Lazy SMP)   │
- ┘

B. NNUE Component:
**┌─ NNUE Evaluation ──────────────┐**
- AccumulatorStack             │
- SIMD/Scalar Inference        │
- Network Architecture         │
- ┘

##### Performance-Critical Paths

- Search → NNUE evaluation
- Move generation → Search
- Transposition table access paths

This design captures both the high-level architecture and the important implementation details that make Serendipity a top-performing chess engine.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef core fill:#2374f7,stroke:#000,stroke-width:2px,color:#fff
    classDef nnue fill:#4CAF50,stroke:#000,stroke-width:2px,color:#fff
    classDef uci fill:#FF9800,stroke:#000,stroke-width:2px,color:#fff
    classDef debug fill:#9E9E9E,stroke:#000,stroke-width:2px,color:#fff
    classDef listener fill:#673AB7,stroke:#000,stroke-width:2px,color:#fff

    %% UCI Layer
    subgraph UCI
        UCI_Main["UCI Interface"]:::uci
        UCI_Options["UCI Options"]:::uci
        UCI_Listener["UCI Listener"]:::uci
        
        UCI_Main --- UCI_Options
        UCI_Main --- UCI_Listener
    end

    %% Search System
    subgraph SearchSystem
        Search["Search System"]:::core
        AlphaBeta["Alpha-Beta Search"]:::core
        MovePicker["Move Ordering"]:::core
        TTable["Transposition Table"]:::core
        ThreadMgr["Thread Management"]:::core
        TimeMgr["Time Management"]:::core
        History["History Tables"]:::core

        Search --> AlphaBeta
        Search --> MovePicker
        Search --> TTable
        Search --> ThreadMgr
        Search --> TimeMgr
        Search --> History
    end

    %% NNUE System
    subgraph NNUESystem
        NNUE["NNUE Main"]:::nnue
        AccStack["Accumulator Stack"]:::nnue
        SIMD["SIMD Inference"]:::nnue
        Scalar["Scalar Inference"]:::nnue

        NNUE --> AccStack
        NNUE --> SIMD
        NNUE --> Scalar
    end

    %% Debug and Listener Systems
    subgraph Support
        Debug["Debugger"]:::debug
        SearchListener["Search Listener"]:::listener
        SearchReport["Search Reports"]:::listener

        SearchListener --> SearchReport
    end

    %% Main Relationships
    UCI_Main --> Search
    Search <--> NNUE
    Search --> Debug
    Search --> SearchListener

    %% Click Events
    click UCI_Main "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/UCI/UCI.java"
    click UCI_Options "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/UCI/UCIOption.java"
    click UCI_Listener "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/UCI/UCIListener.java"
    click Search "https://github.com/xu-shawn/Serendipity/tree/master/src/main/java/org/shawn/games/Serendipity/Search/"
    click AlphaBeta "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/AlphaBeta.java"
    click MovePicker "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/MovePicker.java"
    click TTable "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/TranspositionTable.java"
    click ThreadMgr "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/ThreadManager.java"
    click TimeMgr "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/TimeManager.java"
    click History "https://github.com/xu-shawn/Serendipity/tree/master/src/main/java/org/shawn/games/Serendipity/Search/History/"
    click NNUE "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/NNUE/NNUE.java"
    click AccStack "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/NNUE/AccumulatorStack.java"
    click SIMD "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/NNUE/SIMDInference.java"
    click Scalar "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/NNUE/ScalarInference.java"
    click Debug "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/Debug/Debugger.java"
    click SearchListener "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/Listener/ISearchListener.java"
    click SearchReport "https://github.com/xu-shawn/Serendipity/blob/master/src/main/java/org/shawn/games/Serendipity/Search/Listener/SearchReport.java"
```
