# sueloattack/hand_gesture_game architecture

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

- Interactive diagram: https://gitdiagram.com/sueloattack/hand_gesture_game
- Repository: https://github.com/sueloattack/hand_gesture_game

## Overview

##### Project type and purpose
- From the file tree and the lightweight README badge URL, we see this is a standalone Python-based hand-gesture game / recognition app with a GUI front end, core gameplay/recognition logic, utility modules, a precomputed ML model, and some data files.
- Key indicators:
- app/gui_app.py – the user interface
- app/core_logic.py – game/recognition engine
- models/gesture_prototypes.joblib – a pre-trained ML model
- data/a.csv – (possibly) sample or training data
- config.json – runtime settings

##### File structure
- Top-level entrypoint: main.py
- app/
- gui_app.py – initializes and manages the GUI, captures user gestures
- core_logic.py – processes gesture inputs, interacts with the model, enforces game rules
- utils.py – shared helpers (e.g., image pre-processing, data loading)
- config.json – global settings (e.g., camera resolution, thresholds)
- data/a.csv – data resource (might be used by utils or for logging)
- models/gesture_prototypes.joblib – serialized ML model for inference
- requirements.txt – Python dependencies (e.g., scikit-learn, OpenCV, PyQt/Tkinter)

##### README for additional insights

a. Main components
1. GUI Layer (app/gui_app.py)
2. Application Engine (app/core_logic.py)
3. Utility Services (app/utils.py)
4. Model Storage (models/gesture_prototypes.joblib)
5. Data Store (data/a.csv)
6. Configuration (config.json)
7. External Libraries (listed in requirements.txt)

b. Relationships and data flow
- GUI captures raw input (e.g., camera frames or user clicks)
→ passes to Core Logic
- Core Logic uses Utils for preprocessing (image normalization, data parsing)
- Core Logic loads the ML Model from models/gesture_prototypes.joblib
- Model inference returns recognized gesture
→ Core Logic applies game rules, updates state
→ GUI displays results/feedback
- Config.json is read at startup by main.py or Core Logic to set parameters
- Data CSV may be read or appended by Utils for logging or analytics

c. Architectural patterns
- Layered architecture: Presentation (GUI) → Business Logic (Core) → Data/Model
- Clear separation of concerns: GUI vs. logic vs. utilities vs. storage
- Dependency injection of configuration and model into Core Logic at runtime

d. Key technologies
- Python 3.x
- GUI toolkit (e.g., PyQt, Tkinter)
- scikit-learn or joblib for model loading
- OpenCV or PIL for image capture/processing
- JSON parser for config

- “GUI Layer”
- “Core Logic / Game Engine”
- “Utilities”
- “ML Model Store”
- “Data Store”
- “Configuration Service”
- Input → GUI → Core Logic → Utils → Model
- Model → Core Logic → GUI
- Config JSON → Core Logic
- Data CSV ↔ Utils
- Processing modules in another (e.g., green)
- Storage (model/data) in a third (e.g., orange)
- External libs/dependencies in gray

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Entrypoint
    Main["main.py\n(Application Entrypoint)"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        GUI["GUI Layer"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        Core["Core Logic / Game Engine"]:::logic
        Utils["Utilities"]:::logic
    end

    %% Storage & Configuration
    subgraph "Storage & Config"
        Model["ML Model Store"]:::storage
        Data["Data Store"]:::storage
        Config["Configuration Service"]:::storage
    end

    %% External Dependencies
    ExternalLibs["External Libraries\n(requirements.txt)"]:::external

    %% Data Flows and Dependencies
    Main -->|"orchestrates"| GUI
    Main -->|"orchestrates"| Core
    Main -->|"loads settings from"| Config
    Main -->|"initializes"| Utils

    GUI -->|"captures input"| Core
    Core -->|"uses preprocessing"| Utils
    Utils -->|"reads/writes"| Data
    Core -->|"loads model"| Model
    Model -->|"returns inference"| Core
    Core -->|"updates UI"| GUI
    Config -->|"provides settings"| Core
    ExternalLibs -->|"provides APIs"| GUI
    ExternalLibs -->|"provides APIs"| Core
    ExternalLibs -->|"provides APIs"| Utils

    %% Click Events
    click GUI "https://github.com/sueloattack/hand_gesture_game/blob/main/app/gui_app.py"
    click Core "https://github.com/sueloattack/hand_gesture_game/blob/main/app/core_logic.py"
    click Utils "https://github.com/sueloattack/hand_gesture_game/blob/main/app/utils.py"
    click Model "https://github.com/sueloattack/hand_gesture_game/blob/main/models/gesture_prototypes.joblib"
    click Data "https://github.com/sueloattack/hand_gesture_game/blob/main/data/a.csv"
    click Config "https://github.com/sueloattack/hand_gesture_game/blob/main/config.json"
    click Main "https://github.com/sueloattack/hand_gesture_game/blob/main/main.py"
    click ExternalLibs "https://github.com/sueloattack/hand_gesture_game/blob/main/requirements.txt"

    %% Styles
    classDef presentation fill:#CCE5FF,stroke:#333,stroke-width:1px;
    classDef logic fill:#CCFFCC,stroke:#333,stroke-width:1px;
    classDef storage fill:#FFD2A6,stroke:#333,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px;
```
