# ishaannene/blunderbuss architecture

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

- Interactive diagram: https://gitdiagram.com/ishaannene/blunderbuss
- Repository: https://github.com/ishaannene/blunderbuss

## Overview

##### Overview of the Project
- The BlunderBuss project is a chess engine written entirely in C. According to the README, it’s a version of “Vice Chess” that takes advantage of OpenMP for parallelism.
- Its core function is to implement chess logic including board representation, move generation, evaluation, and parallelized search.

a. Input/Interface Layer:
- UCI and XBoard Interfaces: Represented by the files “uci.c” and “xboard.c”. These serve as entry points for chess commands.
- UI Components: “ui.c” and “io.c” may handle additional input/output aspects.

b. Core Engine Logic:
- Board Representation: Files like “board.c”, “bitboards.c”, and “attack.c” represent the chess board structure using bitboards and define how pieces and attacks are computed.
- Move Generation & Validation: “movegen.c”, “makemove.c”, “validate.c” embody the logic for generating potential moves and ensuring legal moves.
- Search Algorithms: “search.c” is central to the engine’s decision-making; note that OpenMP is likely used here to run parallel search operations.
- Evaluation: “evaluate.c” contains the logic for assessing board positions.
- Auxiliary and Support Functions: “init.c”, “defs.h”, “misc.c” help to initialize data structures (possibly including OpenMP settings) and define common constants or helper functions.

c. Data and Hashing:
- Hash Keys and Transposition: “hashkeys.c” and “polykeys.c”/“polykeys.h” likely implement functions to generate hash keys for board positions and manage an opening book via “polybook.c”.
- Precomputed Data: “data.c” might store pre-calculated look-up tables for fast computation.

d. Additional Tools and Performance:
- Performance Testing: The file “perft.c” is meant to test move generation performance and count positions.
- An Executable File “blunderbuss” (and “blunderbuss.c”) indicates the main executable entry point.

e. Build and Configuration:
- “makefile” is used to build the project, setting up compilation (likely including proper flags for OpenMP).

##### Relationships and Interactions
- The Interfaces (UCI, XBoard, UI) accept external commands and pass them to the Engine Core.
- The Engine Core interacts with the Board, Move Generation, and Search components:
– For each move, the Board is updated using “makemove.c” after verifying legal moves from “validate.c”.
– The Search component uses the Move Generation module and Evaluation functions (from “evaluate.c”) for decision-making. Here, OpenMP directives in search enable parallel evaluation of moves.
- Data components (hash keys, polybook) are used during search to quickly retrieve evaluations and avoid re-calculations.

##### Final Suggestions
- Even if not every minor function is depicted, capture the essential architectural modules and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input/Interface Layer
    subgraph "Input/Interface Layer"
        UCI("UCI Interface"):::interface
        XBoard("XBoard Interface"):::interface
        UI("UI"):::interface
        IO("IO"):::interface
    end

    %% Core Engine Logic
    subgraph "Core Engine Logic"
        %% Board Representation
        subgraph "Board Representation"
            Board("Board Representation"):::core
            Bitboards("Bitboards"):::core
            Attack("Attack"):::core
        end

        %% Move Generation & Validation
        subgraph "Move Generation & Validation"
            MoveGen("MoveGen"):::core
            MakeMove("MakeMove"):::core
            Validate("Validate"):::core
        end

        %% Search & Evaluation
        subgraph "Search & Evaluation"
            Search("Search (OpenMP)"):::core
            Evaluation("Evaluation"):::core
        end

        %% Auxiliary & Support Functions
        subgraph "Auxiliary & Support"
            Init("Init"):::core
            Defs("Defs"):::core
            Misc("Misc"):::core
        end
    end

    %% Data & Hashing
    subgraph "Data & Hashing"
        HashKeys("HashKeys"):::data
        PolyKeys("PolyKeys"):::data
        PolyHeader("PolyHeader"):::data
        PolyBook("PolyBook"):::data
        Precomputed("Precomputed Data"):::data
    end

    %% Additional Tools & Executable
    subgraph "Additional Tools & Executable"
        Perft("Perft"):::tool
        Executable("Executable Entry"):::tool
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        Makefile("Makefile"):::build
    end

    %% Relationships and Data Flow
    UCI -->|"commandData"| Board
    XBoard -->|"commandData"| Board
    UI -->|"commandData"| Board
    IO -->|"commandData"| Board

    Board -->|"moveUpdate"| MoveGen
    Bitboards -->|"bitboardData"| MoveGen
    Attack -->|"attackData"| MoveGen

    MoveGen -->|"generatedMoves"| Search
    MakeMove -->|"applyMove"| Search
    Validate -->|"legalMoves"| Search

    Search -->|"evaluation"| Evaluation
    Evaluation -->|"outputResult"| UI

    %% Auxiliary support to Core modules
    Init -->|"initConfig"| Board
    Defs -->|"definitions"| Board
    Defs -->|"definitions"| Search
    Misc -->|"helpers"| Search

    %% Search interactions with Data & Hashing
    Search -->|"hashLookup"| HashKeys
    Search -->|"polyLookup"| PolyKeys
    Search -->|"polyLookup"| PolyBook
    Search -->|"preComputed"| Precomputed

    %% Additional Tools interactions
    Perft -->|"performanceTest"| MoveGen
    Executable -->|"mainEntry"| UCI

    %% Styles
    classDef interface fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef tool fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for Input/Interface Layer
    click UCI "https://github.com/ishaannene/blunderbuss/blob/main/uci.c"
    click XBoard "https://github.com/ishaannene/blunderbuss/blob/main/xboard.c"
    click UI "https://github.com/ishaannene/blunderbuss/blob/main/ui.c"
    click IO "https://github.com/ishaannene/blunderbuss/blob/main/io.c"

    %% Click Events for Core Engine Logic - Board Representation
    click Board "https://github.com/ishaannene/blunderbuss/blob/main/board.c"
    click Bitboards "https://github.com/ishaannene/blunderbuss/blob/main/bitboards.c"
    click Attack "https://github.com/ishaannene/blunderbuss/blob/main/attack.c"

    %% Click Events for Core Engine Logic - Move Generation & Validation
    click MoveGen "https://github.com/ishaannene/blunderbuss/blob/main/movegen.c"
    click MakeMove "https://github.com/ishaannene/blunderbuss/blob/main/makemove.c"
    click Validate "https://github.com/ishaannene/blunderbuss/blob/main/validate.c"

    %% Click Events for Core Engine Logic - Search & Evaluation
    click Search "https://github.com/ishaannene/blunderbuss/blob/main/search.c"
    click Evaluation "https://github.com/ishaannene/blunderbuss/blob/main/evaluate.c"

    %% Click Events for Core Engine Logic - Auxiliary & Support
    click Init "https://github.com/ishaannene/blunderbuss/blob/main/init.c"
    click Defs "https://github.com/ishaannene/blunderbuss/blob/main/defs.h"
    click Misc "https://github.com/ishaannene/blunderbuss/blob/main/misc.c"

    %% Click Events for Data & Hashing
    click HashKeys "https://github.com/ishaannene/blunderbuss/blob/main/hashkeys.c"
    click PolyKeys "https://github.com/ishaannene/blunderbuss/blob/main/polykeys.c"
    click PolyHeader "https://github.com/ishaannene/blunderbuss/blob/main/polykeys.h"
    click PolyBook "https://github.com/ishaannene/blunderbuss/blob/main/polybook.c"
    click Precomputed "https://github.com/ishaannene/blunderbuss/blob/main/data.c"

    %% Click Events for Additional Tools & Executable
    click Perft "https://github.com/ishaannene/blunderbuss/blob/main/perft.c"
    click Executable "https://github.com/ishaannene/blunderbuss/blob/main/blunderbuss.c"

    %% Click Event for Build & Configuration
    click Makefile "https://github.com/ishaannene/blunderbuss/tree/main/makefile"
```
