# adityamakkar000/signspeak architecture

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

- Interactive diagram: https://gitdiagram.com/adityamakkar000/signspeak
- Repository: https://github.com/adityamakkar000/signspeak

## Overview

##### Project Type and Purpose
- The project is primarily a research and open-source tool addressing real-time ASL translation.
- It comprises both hardware interactions (data glove using flex sensors and microcontroller code) and software pipelines (data collection, preprocessing, training experiments, and model implementations using LSTM, GRU, etc.).

##### Analyzing the File Structure
- Top-Level Structure:
- Files such as .gitignore, LICENSE, and README indicate standard repository practices.
- The requirement file (req.txt) signifies dependency management.
- Key Directories:
- src/dataCollection: Contains the logic for interfacing with the data glove – notably dataCollector.py, glovecode.ino, and stat.py.
- src/experiments: Includes training scripts (LightningTrain.py, RNNTrain.sh, encodertrain.sh) and a dedicated subfolder for experimental data (data/data.csv).
- src/models: Houses different model definitions (GRU.py, LSTM.py, LightningModel.py, encoder.py, generalModels.py), clearly separating the various deep learning architectures.
- src/misc: Contains additional utilities like DataModule.py that may support data manipulation or other supportive functions.

##### Main Components
a. Data Glove & Sensor Hardware:
- Physical hardware (flex sensors on the glove) along with the microcontroller (Arduino MEGA 2560). This component is responsible for capturing finger movements.
- That this hardware sends real-time sensor data (via serial output) to the system.

b. Data Collection Module (Software Side):
- DataCollection module (src/dataCollection) which includes:
- dataCollector.py – for collecting and processing sensor input.
- glovecode.ino – firmware running on the microcontroller.
- stat.py – for any statistical handling or monitoring.

c. Dataset Storage & Preprocessing:
- Dataset (stored in src/experiments/data/data.csv) that is acquired through the glove.
- A preprocessing step if extra operations are performed before training.

d. Experiments & Training Module:
- Training scripts (LightningTrain.py, RNNTrain.sh, encodertrain.sh) which trigger model training.
- The role of the command-line interface in adjusting hyperparameters.

e. Model Definitions & Inference:
- Out the models defined in src/models: LSTM, GRU, Transformer-based, etc.
- How these modules feed into the training pipeline and eventually into the prediction process.

f. Supporting Modules:
- Src/misc/DataModule.py if it serves to support data handling and integration across components.

##### Relationships and Data Flow
- From the Physical Data Glove → Arduino (embedded microcontroller code in glovecode.ino) → Data Collection Module (dataCollector.py within the src/dataCollection directory).
- From the Data Collection Module → Dataset Storage (data.csv in src/experiments/data).
- From Dataset Storage → Experiment/Training Scripts (LightningTrain.py, RNNTrain.sh, encodertrain.sh) in src/experiments.
- From Experiment/Training Scripts → Model Modules in src/models, representing training and evaluation.

##### Architectural Patterns & Design Principles
- Modularity: Separate components (data collection, experimentation, and modeling) are clearly isolated, following a layered approach.
- Pipeline Flow: Emphasizes the sequential nature (from data capture to training) while supporting feedback loops for model optimization.
- Hardware-Software Integration: Demonstrates how low-level sensor data is transformed into high-level model predictions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware"
        A1["Data Glove & Sensors"]:::hardware
        A2["MCU Firmware"]:::hardware
    end

    %% Data Collection Layer
    subgraph "Data Collection Module"
        DC1["Data Collector (dataCollector.py)"]:::datacollect
        DC2["Statistics Monitor (stat.py)"]:::datacollect
        DM["Data Module (DataModule.py)"]:::support
    end

    %% Dataset Storage/Preprocessing Layer
    subgraph "Dataset Storage/Preprocessing"
        D["Dataset (data.csv)"]:::dataset
    end

    %% Experiments & Training Layer
    subgraph "Experiments/Training Scripts"
        E1["LightningTrain.py"]:::experiment
        E2["RNNTrain.sh"]:::experiment
        E3["EncoderTrain.sh"]:::experiment
    end

    %% Models & Inference Layer
    subgraph "Models & Inference Engine"
        M1["GRU.py"]:::models
        M2["LSTM.py"]:::models
        M3["LightningModel.py"]:::models
        M4["Encoder.py"]:::models
        M5["GeneralModels.py"]:::models
    end

    %% Data Flow
    A1 -->|"data_acquisition"| A2
    A2 -->|"send_sensor_data"| DC1
    A2 -->|"send_sensor_data"| DC2
    DC1 -->|"collect_data"| D
    DC2 -->|"monitor_stats"| D
    DM -->|"support_integration"| D
    D -->|"initiate_training"| E1
    D -->|"initiate_training"| E2
    D -->|"initiate_training"| E3
    E1 -->|"model_training"| M1
    E1 -->|"model_training"| M2
    E1 -->|"model_training"| M3
    E1 -->|"model_training"| M4
    E1 -->|"model_training"| M5
    E2 -->|"model_training"| M1
    E2 -->|"model_training"| M2
    E2 -->|"model_training"| M3
    E2 -->|"model_training"| M4
    E2 -->|"model_training"| M5
    E3 -->|"model_training"| M1
    E3 -->|"model_training"| M2
    E3 -->|"model_training"| M3
    E3 -->|"model_training"| M4
    E3 -->|"model_training"| M5

    %% Click Events
    click A2 "https://github.com/adityamakkar000/signspeak/blob/master/src/dataCollection/glovecode.ino"
    click DC1 "https://github.com/adityamakkar000/signspeak/blob/master/src/dataCollection/dataCollector.py"
    click DC2 "https://github.com/adityamakkar000/signspeak/blob/master/src/dataCollection/stat.py"
    click D "https://github.com/adityamakkar000/signspeak/blob/master/src/experiments/data/data.csv"
    click E1 "https://github.com/adityamakkar000/signspeak/blob/master/src/experiments/LightningTrain.py"
    click E2 "https://github.com/adityamakkar000/signspeak/blob/master/src/experiments/RNNTrain.sh"
    click E3 "https://github.com/adityamakkar000/signspeak/blob/master/src/experiments/encodertrain.sh"
    click M1 "https://github.com/adityamakkar000/signspeak/blob/master/src/models/GRU.py"
    click M2 "https://github.com/adityamakkar000/signspeak/blob/master/src/models/LSTM.py"
    click M3 "https://github.com/adityamakkar000/signspeak/blob/master/src/models/LightningModel.py"
    click M4 "https://github.com/adityamakkar000/signspeak/blob/master/src/models/encoder.py"
    click M5 "https://github.com/adityamakkar000/signspeak/blob/master/src/models/generalModels.py"
    click DM "https://github.com/adityamakkar000/signspeak/blob/master/src/misc/DataModule.py"

    %% Styles
    classDef hardware fill:#FF6F61,stroke:#000,stroke-width:2px;
    classDef datacollect fill:#6BCB77,stroke:#000,stroke-width:2px;
    classDef dataset fill:#4D96FF,stroke:#000,stroke-width:2px;
    classDef experiment fill:#FFB74D,stroke:#000,stroke-width:2px;
    classDef models fill:#AB47BC,stroke:#000,stroke-width:2px;
    classDef support fill:#FDD835,stroke:#000,stroke-width:2px;
```
