# nvzqz/sage architecture

> Architecture diagram of the GitHub repository nvzqz/sage, 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/nvzqz/sage
- Repository: https://github.com/nvzqz/sage

## Overview

##### Main Components
- Game Management Module: Represented by Game.swift and supporting classes. This module orchestrates move execution, undo/redo functionalities, and overall game progression.
- Move Generation and Validation: Components that handle generating available moves (using tables and internal representations) as well as validating moves (including special moves like en passant, castling, and pawn promotions).
- Input/Output and Notation Utilities: Modules for FEN (Forsyth–Edwards Notation) and PGN (Portable Game Notation) handling, which are critical for exporting and importing game states.
- Testing and Benchmarking: Although not part of the production architecture, the Tests directory and Benchmark module illustrate how the system is verified and performance measured.
- Playground & Platform Support: The playground and Xcode project elements indicate an interactive development and demonstration component for visualizing chess boards (e.g., board quick look).

##### Relationships and Interactions
- The Board component interacts with Bitboard operations and also supports pretty printing for debugging and visualization.
- The FEN and PGN utilities interact with both the Game and Board components to serialize/deserialize state.
- There is a clear separation between the library’s core logic (inside Sources) and its testing frameworks (Tests), as well as supplementary environments (Benchmark, Playground) used to validate and demonstrate functionality.

##### Architectural Patterns and Design Principles
- Modular Design: Each chess-related concept (board, game state, move, piece) is encapsulated in its own Swift file, promoting separation of concerns.
- API Layer Exposure: Public methods (e.g., availableMoves(), execute(move:)) provide a clean API for external applications integrating Sage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Sage Library Core"
        %% Data Model Subgraph
        subgraph "Data Model"
            Board["Board"]:::dataModel
            Bitboard["Bitboard"]:::dataModel
            Piece["Piece"]:::dataModel
            Move["Move"]:::dataModel
            Square["Square"]:::dataModel
            Rank["Rank"]:::dataModel
            Color["Color"]:::dataModel
            CastlingRights["CastlingRights"]:::dataModel
        end

        %% Domain Logic Subgraph
        subgraph "Domain Logic"
            GameManager["Game Manager"]:::domainLogic
            MoveGen["Move Generation & Validation"]:::domainLogic
            InternalTypes["Internal Types"]:::domainLogic
        end

        %% I/O Utilities Subgraph
        subgraph "I/O Utilities"
            PGN["PGN/Notation Utilities"]:::ioUtilities
            FileUtil["File Utilities"]:::ioUtilities
        end
    end

    %% Supporting Tools
    subgraph "Supporting Tools"
        TestSuite["Test Suite"]:::support
        Benchmark["Benchmark Module"]:::support
        Playground["Playground"]:::support
        XcodeProj["Xcode Project"]:::support
    end

    %% Relationships within Core Library
    GameManager -->|"modifies"| Board
    GameManager -->|"retrievesMoves"| MoveGen
    GameManager -->|"utilizes"| InternalTypes
    MoveGen -->|"interactsWith"| Board
    Board -->|"bitOps"| Bitboard

    %% I/O Utilities interactions
    PGN -->|"serializes"| GameManager
    PGN -->|"readsState"| Board
    FileUtil -->|"handlesIO"| PGN

    %% Supporting Tools interactions with Core Library
    TestSuite -->|"tests"| GameManager
    Benchmark -->|"benchmarks"| GameManager
    Playground -->|"visualizes"| Board
    XcodeProj -->|"supports"| GameManager

    %% Click Events for Data Model Components
    click Board "https://github.com/nvzqz/sage/blob/develop/Sources/Board.swift"
    click Bitboard "https://github.com/nvzqz/sage/blob/develop/Sources/Bitboard.swift"
    click Piece "https://github.com/nvzqz/sage/blob/develop/Sources/Piece.swift"
    click Move "https://github.com/nvzqz/sage/blob/develop/Sources/Move.swift"
    click Square "https://github.com/nvzqz/sage/blob/develop/Sources/Square.swift"
    click Rank "https://github.com/nvzqz/sage/blob/develop/Sources/Rank.swift"
    click Color "https://github.com/nvzqz/sage/blob/develop/Sources/Color.swift"
    click CastlingRights "https://github.com/nvzqz/sage/blob/develop/Sources/CastlingRights.swift"

    %% Click Events for Domain Logic Components
    click GameManager "https://github.com/nvzqz/sage/blob/develop/Sources/Game.swift"
    click MoveGen "https://github.com/nvzqz/sage/blob/develop/Sources/Tables.swift"
    click InternalTypes "https://github.com/nvzqz/sage/blob/develop/Sources/InternalTypes.swift"

    %% Click Events for I/O Utilities
    click PGN "https://github.com/nvzqz/sage/blob/develop/Sources/PGN.swift"
    click FileUtil "https://github.com/nvzqz/sage/blob/develop/Sources/File.swift"

    %% Click Events for Supporting Tools
    click TestSuite "https://github.com/nvzqz/sage/tree/develop/Tests/SageTests/"
    click Benchmark "https://github.com/nvzqz/sage/blob/develop/Benchmark/main.swift"
    click Playground "https://github.com/nvzqz/sage/blob/develop/Sage.playground"
    click XcodeProj "https://github.com/nvzqz/sage/blob/develop/Sage.xcodeproj"

    %% Styles
    classDef dataModel fill:#a3c4f3,stroke:#333,stroke-width:2px;
    classDef domainLogic fill:#a3f3a3,stroke:#333,stroke-width:2px;
    classDef ioUtilities fill:#f3eaa3,stroke:#333,stroke-width:2px;
    classDef support fill:#f3a3a3,stroke:#333,stroke-width:2px;
```
