# souptik-mu/chess-robot architecture

> Architecture diagram of the GitHub repository souptik-mu/chess-robot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souptik-mu/chess-robot
- Repository: https://github.com/souptik-mu/chess-robot

## Overview

##### Project Type and Purpose
- This is a hybrid desktop‐to‐hardware control system: a Python GUI application (CustomTkinter + OpenCV + python-chess) running on a PC that communicates via serial (USB) with an ESP32 microcontroller to drive an LED chessboard.

##### File Structure Analysis
- Top level:
- MAIN.py – application entry point
- requirements.txt – Python dependencies (CustomTkinter, OpenCV, python-chess, pyserial, etc.)
- firmware/ – ESP32 Arduino sketches for LED matrix control
- src/ – Python modules:
- BoardDetection.py – uses OpenCV to detect board state from camera frames
- Game.py – wraps python-chess, enforces move logic and state
- widgets.py – CustomTkinter widgets and main GUI layout

##### Key Technologies and External Interfaces
- GUI layer: CustomTkinter on Python
- Vision layer: OpenCV (camera capture → board grid detection)
- Logic layer: python-chess for move legality, game state
- Communication layer: pyserial over USB → ESP32
- Firmware: Arduino code on ESP32 controlling LED drivers/matrix

##### Main Components and Interactions
a. Camera Input → BoardDetection module → detected board state
b. Board state → Game module → validate moves and update game state
c. Game state → GUI widgets → update on-screen board & controls
d. Game state → Serial communication → ESP32 firmware → physical LED matrix updates
e. User actions in GUI → Game module → (loop back: validate and send to firmware)

##### Architectural Patterns and Design Principles
- Layered pattern: Vision → Logic → Presentation → Hardware interface
- Single Responsibility: each Python module handles one concern
- Event-driven GUI: user input triggers callbacks in widgets.py
- Pipeline for image processing: capture → preprocess → grid detection

##### Final Checklist
- All main components present and labeled
- Notes on external libraries and protocols
- Clear separation (boundary) between PC application and microcontroller hardware

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PC Application Side
    subgraph "PC Application"
        subgraph Vision
            Camera["Camera"]:::hardware
            BD["BoardDetection (OpenCV)"]:::vision
            OC[(OpenCV)]:::external
        end
        subgraph Logic
            GameMod["Game (python-chess)"]:::logic
            PCChess[(python-chess)]:::external
        end
        subgraph Presentation
            Widgets["Widgets (CustomTkinter)"]:::presentation
            Assets["Assets (Themes/Icons)"]:::presentation
        end
        subgraph Communication
            Serial["Serial (UART over USB)"]:::comm
        end
        MAIN["MAIN.py"]:::entry
        Req[(requirements.txt)]:::external
    end

    %% Hardware Side
    subgraph "Hardware (Microcontroller)"
        subgraph Firmware
            FW1["MatrixDriver.ino"]:::hardware
            FW2["MatrixDriverV2.ino"]:::hardware
        end
        ESP["ESP32"]:::hardware
        LED["LED Matrix"]:::hardware
        Circs["Circuits"]:::hardware
    end

    %% Data and Control Flow
    Camera -->|captures frame| BD
    BD -->|detects grid| GameMod
    GameMod -->|validate moves| PCChess
    GameMod -->|update UI| Widgets
    Widgets -->|use assets| Assets
    GameMod -->|send commands| Serial
    Serial -->|UART over USB| FW1
    Serial -->|UART over USB| FW2
    FW1 -->|controls| ESP
    FW2 -->|controls| ESP
    ESP -->|drives| LED

    MAIN --> BD
    MAIN --> GameMod
    MAIN --> Widgets
    MAIN --> Serial
    Req --> MAIN

    %% Click Events
    click BD "https://github.com/souptik-mu/chess-robot/blob/master/src/BoardDetection.py"
    click GameMod "https://github.com/souptik-mu/chess-robot/blob/master/src/Game.py"
    click Widgets "https://github.com/souptik-mu/chess-robot/blob/master/src/widgets.py"
    click MAIN "https://github.com/souptik-mu/chess-robot/blob/master/MAIN.py"
    click Req "https://github.com/souptik-mu/chess-robot/blob/master/requirements.txt"
    click Assets "https://github.com/souptik-mu/chess-robot/blob/master/assets/Theme.json"
    click FW1 "https://github.com/souptik-mu/chess-robot/blob/master/firmware/MatrixDriver.ino"
    click FW2 "https://github.com/souptik-mu/chess-robot/blob/master/firmware/MatrixDriverV2.ino"
    click Circs "https://github.com/souptik-mu/chess-robot/tree/master/Circuits/"

    %% Styles
    classDef vision fill:#add8e6,stroke:#333,stroke-width:1px
    classDef logic fill:#90ee90,stroke:#333,stroke-width:1px
    classDef presentation fill:#ffa500,stroke:#333,stroke-width:1px
    classDef comm fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef hardware fill:#f08080,stroke:#333,stroke-width:1px
    classDef entry fill:#d3d3d3,stroke:#333,stroke-width:1px
```
