# orionramos/hpis_app_code architecture

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

- Interactive diagram: https://gitdiagram.com/orionramos/hpis_app_code
- Repository: https://github.com/orionramos/hpis_app_code

## Overview

##### Project Type and Purpose
- HPIS is a distributed, real-time human-prosthesis interaction system.
- It comprises an embedded device (ESP32), a Python WebSocket server (orchestration layer), several Python clients (control apps + simulations), a Unity application (visualization), and auxiliary modules (HRI audio strategies, YOLO).

##### Main Components
a. Hardware Layer
- ESP32 device (firmware in ESP/main: `main.ino`, `config.h`, `wifi_communicator.h`)
- (Optional) ESP32 simulation client (`ClienteESP32.py`)
b. Server Layer
- WebSocketServer (`Python/Main/WebsocketServer.py`) – central hub
- HRControl client (`Python/Main/HRControl.py`) – fetches heart-rate via Pulsoid API
- HPISControl client (`Python/Main/HPIS_Control.py`) – user GUI/CLI for selecting participant/HRI strategy
- launch_manager, client_data_recorder (supporting scripts)
c. Auxiliary Services / Modules
- HRI_Strategies (`Python/HRI_Strategies/HRI_Audio_Creation.py` + JSON + generated MP3s)
- YOLO object-detection module (`Python/YOLO/YOLO.py`, `seting.py`)
d. Client Layer
- Unity App (Unity packages + `lecturaJSONDatabase.py`, `feedback_data_named.json`)
- Unity simulation client (`Python/Simulation/clientUnitySimulation.py`)
e. Deployment / Configuration
- `requirements.txt`, `install_requirements.py`
- Arduino library dependencies (ArduinoJson, ESPping)

##### Relationships and Data Flows
- ESP32 ↔ WebSocketServer
- ESP32 streams EMG pulses to server
- Server sends back “grip type” commands (pulse-train)
- HRControl ↔ Pulsoid API ↔ WebSocketServer
- HRControl polls Pulsoid → WS server
- HPISControl ↔ WebSocketServer
- User selections (participant/strategy/activity) → server
- WebSocketServer ↔ Unity App (or Simulation)
- Server pushes processed data (EMG, HR, strategy cues) → Unity
- HPISControl → HRI_Strategies module
- On strategy selection, invokes audio generation → MP3 files served or played
- (Optional) YOLO ⚙ WebSocketServer
- Object detection results feed into HRI logic

##### Architectural Patterns / Design Principles
- Event-driven / message-oriented via WebSockets
- Modular separation:
- Hardware clients vs. software clients
- Core orchestration (server) vs. auxiliary processing (audio, vision)
- Simulations decoupled (ESP32 & Unity) for offline testing
- Clear separation of concerns:
- Data ingestion (EMG, HR)
- Control logic (HPISControl)
- Visualization (Unity)
- Extensibility points (HRI_Strategies, YOLO)

- Notes on technology: Python 3.x, WebSocket library, ArduinoJson, Unity.
- Modular grouping to reflect directory structure.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hardware & Simulation"
        ESP32["ESP32 Hardware\n(main.ino, config.h, wifi_communicator.h, my_wifi.h)"]:::hardware
        ESP32_Sim["ESP32 Simulation\n(ClienteESP32.py)"]:::simulation
    end

    subgraph "Control Clients"
        HPISControl["HPISControl Client\n(HPIS_Control.py)"]:::client
        HRControl["HRControl Client\n(HRControl.py)"]:::client
    end

    WS["WebSocketServer\n(WebsocketServer.py)"]:::server

    subgraph "Server Support"
        LaunchMgr["Launch Manager\n(launch_manager.py)"]:::server
        DataRec["Client Data Recorder\n(client_data_recorder.py)"]:::server
    end

    subgraph "Unity & Simulation"
        UnityApp["Unity Application\n(lecturaJSONDatabase.py, feedback_data_named.json)"]:::unity
        UnitySim["Unity Simulation Client\n(clientUnitySimulation.py)"]:::simulation
    end

    subgraph "Auxiliary Modules"
        HRI["HRI Audio Strategies\n(HRI_Audio_Creation.py, audio_estrategies.json, audios_generados/)"]:::aux
        YOLO["YOLO Object-Detection\n(YOLO.py, seting.py)"]:::aux
    end

    Pulsoid["Pulsoid API"]:::external

    %% Data Flows
    ESP32 -->|"\nWebSocket: EMG → Server"| WS
    WS -->|"\nWebSocket: Grip Cmd → ESP32"| ESP32

    ESP32_Sim -->|"\nWS: EMG Sim → Server"| WS
    WS -->|"\nWS: Cmd Sim → ESP32 Sim"| ESP32_Sim

    HPISControl -->|"\nWS: User Selections"| WS
    HRControl -->|"\nHTTP REST: Poll HR"| Pulsoid
    Pulsoid -->|"\nREST: HR Data →"| HRControl
    HRControl -->|"\nWS: HR Data → Server"| WS

    WS -->|"\nWS: Streams (EMG, HR, Cues)"| UnityApp
    UnitySim -->|"\nSim Data → Server"| WS
    WS -->|"\nWS: to Sim"| UnitySim

    HPISControl -->|"\nInvoke Strategy"| HRI
    HRI -->|"\nMP3 Assets →"| UnityApp

    YOLO -->|"\nVision Data →"| WS

    LaunchMgr -->|"\nStartup Orchestration"| WS
    WS -->|"\nLog Events →"| DataRec

    %% Deployment
    Config["Deployment Config\n(requirements.txt)"]:::storage

    %% Click Events
    click ESP32 "https://github.com/orionramos/hpis_app_code/blob/main/ESP/main/main.ino"
    click ESP32_Sim "https://github.com/orionramos/hpis_app_code/blob/main/Python/Simulation/ClienteESP32.py"
    click WS "https://github.com/orionramos/hpis_app_code/blob/main/Python/Main/WebsocketServer.py"
    click HPISControl "https://github.com/orionramos/hpis_app_code/blob/main/Python/Main/HPIS_Control.py"
    click HRControl "https://github.com/orionramos/hpis_app_code/blob/main/Python/Main/HRControl.py"
    click LaunchMgr "https://github.com/orionramos/hpis_app_code/blob/main/Python/Main/launch_manager.py"
    click DataRec "https://github.com/orionramos/hpis_app_code/blob/main/Python/Main/client_data_recorde.py"
    click HRI "https://github.com/orionramos/hpis_app_code/blob/main/Python/HRI_Strategies/HRI_Audio_Creation.py"
    click YOLO "https://github.com/orionramos/hpis_app_code/blob/main/Python/YOLO/YOLO.py"
    click UnityApp "https://github.com/orionramos/hpis_app_code/blob/main/Unity/lecturaJSONDatabase.py"
    click UnitySim "https://github.com/orionramos/hpis_app_code/blob/main/Python/Simulation/clientUnitySimulation.py"
    click Config "https://github.com/orionramos/hpis_app_code/blob/main/requirements.txt"

    %% Styles
    classDef hardware fill:#AEDFF7,stroke:#0288D1,stroke-width:1px;
    classDef simulation fill:#E0E0E0,stroke:#616161,stroke-width:1px;
    classDef server fill:#C8E6C9,stroke:#388E3C,stroke-width:1px;
    classDef client fill:#B2EBF2,stroke:#00796B,stroke-width:1px;
    classDef aux fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px;
    classDef external fill:#F8BBD0,stroke:#C2185B,stroke-width:1px;
    classDef unity fill:#FFF9C4,stroke:#F9A825,stroke-width:1px;
    classDef storage fill:#FFECB3,stroke:#FFB300,stroke-width:1px;
```
