# prashantsub45/hand_gestured_sound_system-hgss architecture

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

- Interactive diagram: https://gitdiagram.com/prashantsub45/hand_gestured_sound_system-hgss
- Repository: https://github.com/prashantsub45/hand_gestured_sound_system-hgss

## Overview

##### Project Type and Purpose
- This is a full-stack web application called “Hand Gestured Sound System” (HGSS).
- Purpose: allow users to control music playback through hand gestures captured by a webcam.
- Key technologies: Python (Flask), OpenCV & cvzone (gesture recognition), HTML/CSS/JS for the UI, optional Node.js server stub.

##### File Structure
Top-level
- app.py           – main Flask application entry point
- .gitignore       – ignore rules
- README.md        – project description
back/
- app.js           – optional Node.js backend logic
- package.json     – Node project metadata
gesture_engine/
- cam.py           – capture video & process gestures via OpenCV/cvzone
- endapi.py        – Flask API endpoint(s) for gesture results
- try.csv          – optional dataset/log
static/
- images/          – UI assets
- music/           – .mp3 files used by the player
- index.js         – frontend JS (receives gesture events, controls audio)
- style.css        – CSS styles
templates/
- index.html       – Jinja2 template for the main UI

##### Insights from the README
- The Flask backend serves the HTML UI and static assets, and also launches the gesture engine to continuously analyze webcam feed.
- endapi.py exposes endpoints that front-end JS can poll or receive via WebSockets (if extended) with gesture commands (play, pause, next, previous).
- No external database; state is ephemeral in memory.

a. Main Components
1. Webcam (hardware)
2. Gesture Engine (cam.py)
3. Flask Backend (app.py + endapi.py)
4. Frontend UI (index.html + index.js + style.css)
5. Static Assets & Music Store (static/images, static/music)
6. (Optional) Node.js Server in back/
b. Relationships & Data Flow
- Webcam → Gesture Engine: raw video frames streamed.
- Gesture Engine → Flask API: POST or WebSocket message with recognized gesture event.
- Flask API → Frontend JS: HTTP response or real-time push of gesture commands.
- Frontend JS → Audio Player: JS DOM API to play/pause/skip .mp3 files.
- Flask → Frontend: serves index.html and static files over HTTP.
c. Architectural Patterns & Principles
- MVC-style separation:
– Model: gesture detection logic (OpenCV, cvzone)
– View: HTML/CSS/JS UI
– Controller: Flask routes in app.py/endapi.py
- Single-process server: Python process handles both web server and camera capture.
- Optional microservice stub: separate Node.js backend in back/ (if adopted)
d. Key Technologies & Libraries
- Python: Flask, OpenCV, cvzone, NumPy
- JavaScript: Frontend logic, optional Node.js/Express
- HTML/CSS: UI layout & styling

##### Detail
- Python modules (app.py vs. endapi.py vs. cam.py) as separate nodes if needed.
- That static files are served by Flask’s static folder configuration.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Webcam["Webcam"]:::hardware
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        App["Flask Backend\n(app.py)"]:::backend
        Cam["Gesture Engine\n(cam.py)"]:::backend
        EndAPI["Gesture Engine API\n(endapi.py)"]:::backend
        NodeService["Optional Node.js Service\n(app.js)"]:::backend
        StaticStore["Static Assets Store\n(images, music)"]:::storage
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Template["Frontend UI Template\n(index.html)"]:::frontend
        JS["Frontend JS Logic\n(index.js)"]:::frontend
        CSS["Frontend Stylesheet\n(style.css)"]:::frontend
        AudioPlayer["Audio Player\n(DOM API)"]:::frontend
    end

    %% Interactions
    Webcam -->|"video frames"| Cam
    Cam -->|"JSON gesture event"| EndAPI
    EndAPI -->|"HTTP POST/GET JSON"| App
    App -->|"HTTP GET /"| Template
    App -->|"HTTP GET /static/*"| JS
    App -->|"HTTP GET /static/*"| CSS
    App -->|"Serves assets"| StaticStore
    JS -->|"control commands"| AudioPlayer

    %% Click Events
    click Cam "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/gesture_engine/cam.py"
    click EndAPI "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/gesture_engine/endapi.py"
    click App "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/app.py"
    click Template "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/templates/index.html"
    click JS "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/static/index.js"
    click CSS "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/static/style.css"
    click StaticStore "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/tree/main/static/images"
    click NodeService "https://github.com/prashantsub45/hand_gestured_sound_system-hgss/blob/main/back/app.js"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,color:#000
    classDef frontend fill:#90EE90,stroke:#000,color:#000
    classDef storage fill:#D3D3D3,stroke:#000,color:#000
    classDef hardware fill:#FFA500,stroke:#000,color:#000
```
