# riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting architecture

> Architecture diagram of the GitHub repository riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting
- Repository: https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting

## Overview

##### Project Type and Purpose
- From the README and file tree, this is a Python-based web application built with Streamlit. It serves as a “Personal AI Trainer” that:
- Provides a UI (via Streamlit) for users to upload exercise videos or use a webcam
- Performs real-time pose estimation (MediaPipe)
- Extracts features (angles/distances) and classifies exercises (LSTM/BiLSTM models)
- Counts repetitions
- Offers a chatbot interface (OpenAI API via LangChain)

##### File Structure
- Top-level scripts:
- main.py: entry point running the Streamlit app (UI + controller)
- ExerciseAiTrainer.py, AiTrainer_utils.py, PoseModule2.py: core CV and pose-processing modules
- chatbot.py: wraps OpenAI GPT-3.5-turbo for fitness Q&A
- extract_features.py, create_sequence_of_features.py, train_bidirectionallstm.py: offline feature extraction & model-training pipeline
- Pretrained assets:
- .h5 (model), .pkl (scaler, encoder)
- Config/environments:
- environment.yml, requirements.txt, packages.txt

##### Key Architecture Insights from the README
- Modular but monolithic Python backend
- Streamlit serves both frontend and backend in a single process
- MediaPipe for pose landmarks → utilities to compute angles/distances → BiLSTM classification → counting logic
- Chatbot integrated into same app, calling OpenAI API
- Offline training pipeline separated from runtime app

a. Main Components
- Streamlit UI (web client)
- Backend Orchestrator (main.py)
- Pose Estimation Module (PoseModule2)
- Feature Extraction & Preprocessing (AiTrainer_utils, extract_features)
- Classification Model (BiLSTM loaded from .h5 + .pkl)
- Repetition Counting Logic (ExerciseAiTrainer)
- Chatbot Service (chatbot.py → OpenAI API)
- Offline Training Pipeline (extract_features.py → create_sequence_of_features.py → train_bidirectionallstm.py)
b. Relationships & Data Flows
- User action (video upload / webcam) → Streamlit UI
- UI → calls backend orchestrator
- Orchestrator → PoseModule2 to get landmarks
- Landmarks → AiTrainer_utils for feature computation
- Features → classification model → predicted exercise
- Prediction + feature stream → ExerciseAiTrainer counter → repetition count
- UI displays count, form feedback, charts
- Chatbot widget → backend calls chatbot.py → external OpenAI API → response → UI
- Models & scalers loaded once at startup (shared resources)
c. Architectural Patterns / Principles
- Modular layering: UI layer, processing layer (CV & feature), ML inference layer, external API integration
- Single-process monolith (Streamlit)
- Offline/online separation: training pipeline vs inference pipeline
d. Key Technologies & Frameworks
- Streamlit (UI + server)
- MediaPipe (pose estimation)
- OpenCV (video handling)
- TensorFlow / Keras (LSTM & BiLSTM)
- LangChain + OpenAI API (Chatbot)
- Python 3.7+, virtualenv

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        StreamlitUI["Streamlit UI / Backend Orchestrator"]:::frontend
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        direction TB
        PoseModule2["PoseModule2 Module"]:::processing
        AiTrainer_utils["Feature Extraction Utilities"]:::processing
        ExerciseAiTrainer["Repetition Counting Logic"]:::processing
        Chatbot["Chatbot Service"]:::processing
    end

    %% ML Artifacts
    subgraph "ML Artifacts"
        direction TB
        ModelFile[".h5 Classification Model"]:::artifact
        Scaler[".pkl Scaler"]:::artifact
        Encoder[".pkl Label Encoder"]:::artifact
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
    end

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        direction TB
        ExtractFeatures["extract_features.py"]:::offline
        CreateSeq["create_sequence_of_features.py"]:::offline
        TrainModel["train_bidirectionallstm.py"]:::offline
    end

    %% Runtime Inference Flow
    StreamlitUI -->|video frames| PoseModule2
    PoseModule2 -->|landmarks| AiTrainer_utils
    AiTrainer_utils -->|feature vector| ModelFile
    ModelFile -->|prediction| ExerciseAiTrainer
    ExerciseAiTrainer -->|repetition count| StreamlitUI

    %% Model Loading
    Scaler -.->|scaling features| AiTrainer_utils
    Encoder -.->|decode labels| ModelFile

    %% Chatbot Flow
    StreamlitUI -->|chat query| Chatbot
    Chatbot -->|API call| OpenAI
    OpenAI -->|response| Chatbot
    Chatbot -->|chat response| StreamlitUI

    %% Offline Pipeline Flow
    ExtractFeatures -->|raw data| CreateSeq
    CreateSeq -->|sequences| TrainModel
    TrainModel -->|trained model| ModelFile
    TrainModel -->|scaler artifact| Scaler
    TrainModel -->|label encoder| Encoder

    %% Click Events
    click StreamlitUI "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/main.py"
    click PoseModule2 "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/PoseModule2.py"
    click AiTrainer_utils "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/AiTrainer_utils.py"
    click ExerciseAiTrainer "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/ExerciseAiTrainer.py"
    click Chatbot "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/chatbot.py"
    click ExtractFeatures "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/extract_features.py"
    click CreateSeq "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/create_sequence_of_features.py"
    click TrainModel "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/train_bidirectionallstm.py"
    click ModelFile "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/final_forthesis_bidirectionallstm_and_encoders_exercise_classifier_model.h5"
    click Scaler "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/thesis_bidirectionallstm_scaler.pkl"
    click Encoder "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/thesis_bidirectionallstm_label_encoder.pkl"
    click environment.yml "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/environment.yml"
    click requirements.txt "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/requirements.txt"
    click packages.txt "https://github.com/riccardoriccio/fitness-ai-trainer-with-automatic-exercise-recognition-and-counting/blob/main/packages.txt"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9,color:#1B2631,stroke-width:1px;
    classDef processing fill:#D5F5E3,stroke:#27AE60,color:#145A32,stroke-width:1px;
    classDef artifact fill:#F9E79F,stroke:#D68910,color:#7E5109,stroke-width:1px;
    classDef offline fill:#EBDEF0,stroke:#884EA0,color:#4A235A,stroke-width:1px;
    classDef external fill:#D5DBDB,stroke:#7F8C8D,color:#2C3E50,stroke-width:1px;
```
