# iman-zamani/chess-gui-for-uci architecture

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

- Interactive diagram: https://gitdiagram.com/iman-zamani/chess-gui-for-uci
- Repository: https://github.com/iman-zamani/chess-gui-for-uci

## Overview

##### Project type and purpose
- This is a desktop GUI application (“Chess-GUI-for-UCI”) built in C++ with SFML, whose job is to let a human or two UCI-compatible chess engines play against each other. It is not a web app or microservices system but a single process with loosely coupled modules.

##### File structure
- Top-level files:
- CMakeLists.txt – build system definition
- src/ – all C++ source and header files (board, piece, configuration, main)
- images/ – static assets (screenshot)
- Pattern: a modular, layered desktop app with a model (Board, Piece, Values), a controller/engine adapter (UCI logic in main.cpp + configuration), and a view (SFML rendering of board/pieces).

##### Key architectural insights from README
- Uses SFML 2.6 for cross-platform graphics and window/event management
- Spawns and communicates with external UCI engines via stdin/stdout pipelines
- Configuration subsystem to select engines and options

##### Main components
a. Application Entrypoint (main.cpp)
b. Game Controller / UCI Engine Adapter
- UCIProcessManager: launches engine processes, sends/receives commands
c. Configuration Manager (configuration.cpp/.hpp)
d. Model Layer (board.cpp/.hpp, piece.cpp/.hpp, values.hpp)
- ChessBoard, ChessPiece, Move generation state
e. View Layer (SFML Renderer)
- Window Manager, Event Loop, Drawing Subsystem
f. Resource Manager (build/Resources Python scripts + picesTexture.hpp, boardColorGenerator.py, targetSquareGenerator.py)
g. External Dependencies
- SFML library
- UCI-compatible chess engine executables

##### Relationships and interactions
- On launch, main() reads config → instantiates ConfigurationManager
- ConfigurationManager tells UCIProcessManager which engines to load
- GameController orchestrates move requests: sends “go” commands to engines, receives best moves
- GameController updates Model (Board + Piece positions)
- SFML handles window events (mouse clicks for human moves) and passes them back into GameController

##### Architectural patterns and design principles
- Layered architecture: UI (View) ↔ Controller ↔ Model
- Adapter pattern for UCI engine processes
- Build-time resource generation (data-driven UI)
- Single-process desktop app with external process spawning for engines

##### Essential elements to capture
- Module boundaries: src vs. build/Resources
- External process boundary: UCI engine executables vs. main application
- Data flows: user input → controller → engine → model update → view redraw
- Build-time vs. run-time components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System and Resource Pipeline
    subgraph "Build Pipeline"
        direction TB
        CMake["CMakeLists.txt"]:::build
        subgraph "Resource Generation"
            direction TB
            ColorScript["boardColorGenerator.py"]:::resource
            TargetScript["targetSquareGenerator.py"]:::resource
            TextureHeader["picesTexture.hpp"]:::resource
        end
    end

    %% Runtime Modules
    subgraph "Runtime Application"
        direction TB
        subgraph "Controller Layer"
            direction TB
            MainEntrypoint["main.cpp (Entry)"]:::controller
            UCIProcessManager["UCIProcessManager (Adapter)"]:::controller
        end
        subgraph "Configuration"
            direction TB
            ConfigCPP["configuration.cpp"]:::controller
            ConfigHPP["configuration.hpp"]:::controller
        end
        subgraph "Model Layer"
            direction TB
            ChessBoard["ChessBoard"]:::model
            ChessPiece["ChessPiece"]:::model
            MoveValues["Move Definitions"]:::model
        end
        subgraph "View Layer"
            direction TB
            SFMLWindow["SFML Window Manager"]:::view
            EventLoop["Event Loop"]:::view
            Renderer["Drawing Subsystem"]:::view
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        SFML["SFML Library"]:::external
        UCIEngine["UCI Engine Executables"]:::external
    end

    %% Connections
    CMake -->|runs scripts| ColorScript
    CMake -->|runs scripts| TargetScript
    ColorScript -->|generates header| TextureHeader
    TargetScript -->|generates header| TextureHeader
    CMake -->|compiles| MainEntrypoint

    MainEntrypoint -->|reads config| ConfigCPP
    ConfigCPP -->|uses| ConfigHPP
    ConfigCPP -->|instructs| UCIProcessManager
    UCIProcessManager -->|spawn via STDIN/STDOUT| UCIEngine
    UCIProcessManager -->|updates| ChessBoard
    UCIProcessManager -->|updates| ChessPiece
    UCIProcessManager -->|uses move defs| MoveValues

    ChessBoard -->|state read| Renderer
    ChessPiece -->|state read| Renderer
    MoveValues -->|state read| Renderer

    SFMLWindow -->|handles events| EventLoop
    EventLoop -->|user input| MainEntrypoint
    Renderer -->|draw calls| SFMLWindow

    TextureHeader -->|provides textures/colors| Renderer

    SFML -->|graphics API| SFMLWindow

    %% Click Events
    click MainEntrypoint "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/main.cpp"
    click UCIProcessManager "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/main.cpp"
    click ConfigCPP "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/configuration.cpp"
    click ConfigHPP "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/configuration.hpp"
    click ChessBoard "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/board.cpp"
    click ChessBoard "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/board.hpp"
    click ChessPiece "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/piece.cpp"
    click ChessPiece "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/piece.hpp"
    click MoveValues "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/values.hpp"
    click SFMLWindow "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/main.cpp"
    click EventLoop "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/main.cpp"
    click Renderer "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/src/main.cpp"
    click TextureHeader "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/build/Resources/picesTexture.hpp"
    click ColorScript "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/build/Resources/boardColorGenerator.py"
    click TargetScript "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/build/Resources/targetSquareGenerator.py"
    click CMake "https://github.com/iman-zamani/chess-gui-for-uci/blob/main/CMakeLists.txt"

    %% Styles
    classDef controller fill:#fdd,stroke:#f00
    classDef model fill:#dfd,stroke:#0a0
    classDef view fill:#ddf,stroke:#00f
    classDef resource fill:#ffd,stroke:#aa0
    classDef build fill:#ddd,stroke:#555
    classDef external fill:#fdf,stroke:#a0a
```
