# gaxxrav/isl-translator architecture

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

- Interactive diagram: https://gitdiagram.com/gaxxrav/isl-translator
- Repository: https://github.com/gaxxrav/isl-translator

## Overview

##### Project type and purpose
- From the file tree and requirements.txt, we see:
- A single Python service (no separate “frontend” folder).
- An ML-based “translator” that classifies keypoints (likely from video or images) and generates a response.
- Key files: app.py (entrypoint), response.py (business logic), model/keypoint_classifier (trained models), utils/cvfpscalc (utilities).
- Therefore, this is a backend microservice (or standalone application) that exposes an API (probably via Flask or FastAPI, as indicated by requirements.txt) to perform real‐time or batch gesture/keypoint translation.

##### File structure
- Top‐level:
- translator/app.py – the API server
- translator/response.py – orchestrates model output → user response
- translator/model – holds the ML inference logic
– keypoint_classifier.py + several model files (.h5, .tflite, .csv)
- translator/utils – helper functions (cvfpscalc)
- requirements.txt – identifies all external dependencies (Flask or FastAPI, TensorFlow, OpenCV, NumPy, etc.)
- No database or persistent storage is present, so it is a stateless inference service.

##### README
- The README is a placeholder, so we rely on code structure and requirements.txt for insights.

a. Main components:
1. Client / Consumer
– Could be a CLI, web client, or IoT device that sends images/frames.
2. API Layer (translator/app.py)
– Accepts HTTP requests, dispatches to the translation service.
3. Preprocessing & Utilities (translator/utils)
– E.g., frame rate calculation, cropping, normalization.
4. Keypoint Detection & Feature Extraction
– If any upstream detector (e.g., MediaPipe), call it here (not shown in file tree, but often implied).
5. Classifier Service (translator/model/keypoint_classifier.py + model files)
– Loads the .h5/.tflite models and label encoders, runs inference.
6. Response Generator (translator/response.py)
– Maps classification results to user‐facing strings, commands, or JSON.
7. Response to Client
– Returns JSON or other payload via API.

b. Relationships & interactions:
– Client → HTTP (POST image/frame) → API Layer
– API Layer → calls Preprocessing & Utilities → normalized data
– Preprocessed data → Model Inference → classification result
– Classification → Response Generator → final output
– API Layer → returns output to Client

c. Architectural patterns:
– Layered architecture (API → Service → Model → Utils)
– Stateless microservice: no persistent state stored between calls
– Dependency injection of models at startup (in app.py)

d. Key technologies/libraries (from requirements.txt):
– Flask or FastAPI (for HTTP API)
– TensorFlow / TensorFlow Lite (model loading/inference)
– NumPy / SciPy (data handling)
– OpenCV (image processing, via cvfpscalc utility)

##### Starting from requirements.txt
- Parse requirements.txt first to list all frameworks and libraries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    client["Client / Consumer"]:::external

    subgraph "Microservice Container"
        direction TB
        API["HTTP API (app.py)"]:::code
        Utils["Preprocessing Utilities\n(cvfpscalc.py)"]:::util
        ModelPkg["Model Package\n(__init__.py)"]:::code
        Classifier["Keypoint Classifier\n(keypoint_classifier.py)"]:::ml
        ModelArtifacts["Model Artifacts\n(.h5, .tflite,\n.csv, .npy)"]:::ml
        Response["Response Generator\n(response.py)"]:::code
        Dependencies["Dependencies\n(requirements.txt)"]:::dep
        Documentation["Documentation\n(README.md)"]:::doc
    end

    client -->|"HTTP POST image/frame"| API
    API -->|"calls"| Utils
    Utils -->|"preprocessed data"| ModelPkg
    ModelPkg -->|"loads & calls"| Classifier
    Classifier -->|"loads models"| ModelArtifacts
    Classifier -->|"classification result"| Response
    Response -->|"JSON response"| API
    API -->|"HTTP response"| client

    click API "https://github.com/gaxxrav/isl-translator/blob/main/translator/app.py"
    click Utils "https://github.com/gaxxrav/isl-translator/blob/main/translator/utils/cvfpscalc.py"
    click ModelPkg "https://github.com/gaxxrav/isl-translator/blob/main/translator/model/__init__.py"
    click Classifier "https://github.com/gaxxrav/isl-translator/blob/main/translator/model/keypoint_classifier/keypoint_classifier.py"
    click ModelArtifacts "https://github.com/gaxxrav/isl-translator/tree/main/translator/model/keypoint_classifier/"
    click Response "https://github.com/gaxxrav/isl-translator/blob/main/translator/response.py"
    click Dependencies "https://github.com/gaxxrav/isl-translator/blob/main/translator/requirements.txt"
    click Documentation "https://github.com/gaxxrav/isl-translator/blob/main/translator/README.md"

    classDef code fill:#D0E1F9,stroke:#004085,color:#0C2D48
    classDef ml fill:#E2F0D9,stroke:#234D20,color:#0B3D0B
    classDef util fill:#FFF2CC,stroke:#7F6000,color:#594300
    classDef dep fill:#FDE9D9,stroke:#A71D2A,color:#5B0F00
    classDef doc fill:#F4CCCC,stroke:#660000,color:#330000
    classDef external fill:#EAF2F8,stroke:#0C5460,color:#0B3D48
```
