# hirak214/smartstride-tredmill_accessory architecture

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

- Interactive diagram: https://gitdiagram.com/hirak214/smartstride-tredmill_accessory
- Repository: https://github.com/hirak214/smartstride-tredmill_accessory

## Overview

##### Project Type & Purpose
- SmartStride is an end-to-end IoT solution: hardware (ESP32 device + sensors + BLE), embedded firmware, AI/ML model training & inference, Python/FastAPI backend, PostgreSQL database, plus mobile/web clients.
- It “smartens” ordinary treadmills by measuring speed/inclination, sending data to a server that runs LSTM models to personalize workouts, then feeds recommendations back to the user via a mobile app or web dashboard.

##### File‐Structure Analysis
- hardware/firmware: Arduino‐based ESP32 code for sensors (MPU6050, LDRs, OLED) and Bluetooth.
- software/backend: FastAPI main.py + requirements.txt + example.html.
- software/training: Jupyter notebooks & scripts (model development & testing).
- mobile-app: initial MIT App Inventor, planned Flutter.
- docs/: architecture, installation, research, publications.
- media/: images, renders, videos for documentation.

##### Key README Insights
- Tech stack: ESP32, Arduino IDE, TensorFlow LSTM, FastAPI, PostgreSQL, BLE, I2C.

a. Main Components (grouped by layer)
- Hardware Layer (Edge Device)
– ESP32 microcontroller (firmware)
– Sensors: MPU6050 Gyroscope, LDR Speed Sensors
– OLED Display
– Bluetooth Low Energy module
- Communication Layer
– BLE link (ESP32 ↔ Mobile App)
- AI/ML Layer
– Training Pipeline (Jupyter notebooks under software/training)
– LSTM Speed Prediction Model
– LSTM Inclination Model
- Backend Layer
– FastAPI service (software/backend/main.py)
– PostgreSQL database
- Client Layer
– Mobile App (MIT App Inventor & future Flutter)
– Web Dashboard (example.html + FastAPI docs)

b. Relationships & Data Flows
1. Firmware reads sensors → preprocesses → sends telemetry over BLE.
2. Mobile App receives BLE data → displays live metrics → forwards JSON to FastAPI via REST.
3. FastAPI routes:
- Stores raw data in PostgreSQL
- Invokes LSTM models for real-time speed/inclination recommendations
- Returns recommendations to client
4. Web Dashboard polls FastAPI for metrics & model outputs.
5. Offline training: notebooks in software/training pull historic data, train or retrain LSTM models, then serialize and deploy model artifacts to backend.

c. Architectural Patterns & Principles
- Layered Architecture: Edge (hardware/firmware), Communication (BLE), Application (API + ML), Presentation (mobile/web), Data (DB).
- Separation of Concerns:
- Firmware only handles real-time sensor I/O.
- ML pipeline separated from inference (notebooks vs. model serving).
- Backend decouples storage, inference, and API routing.
- Asynchronous I/O in FastAPI for low-latency processing (<100ms).
- Modular firmware sketches per feature (see hardware/firmware subfolders).

d. Key Technologies & Libraries
- ESP32 + Arduino IDE (firmware)
- BLESerial, Adafruit Sensor Libraries (I2C)
- TensorFlow/Keras LSTM
- FastAPI, Uvicorn (REST API)
- PostgreSQL (psycopg2 or async driver)
- Jupyter, Pandas, NumPy, Scikit-learn (training pipeline)
- Mobile: MIT App Inventor; Flutter (future)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Mobile["Mobile App"]:::client
        Web["Web Dashboard"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["FastAPI Service\n(Python 3.8+)"]:::api
    end

    %% Core Services
    subgraph "Core Services"
        Model["Model Inference\n(LSTM Speed & Inclination)"]:::ml
        DB["PostgreSQL Database"]:::db
    end

    %% Offline Training
    subgraph "Offline Training"
        Training["Training Pipeline"]:::ml
    end

    %% Communication Layer
    subgraph "Communication Layer"
        BLE["BLE Link"]:::comm
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        Edge["ESP32 Firmware"]:::hardware
    end

    %% Real-time Data Flow
    Edge -->|"sensor data"| BLE
    BLE -->|"BLE telemetry"| Mobile
    Mobile -->|"REST API (JSON)"| API
    API -->|"store raw data"| DB
    API -->|"invoke inference"| Model
    API -->|"return recommendations"| Mobile
    API -->|"return recommendations"| Web
    Web -->|"poll metrics & outputs"| API

    %% Offline Training Flow
    DB -.->|"historical data"| Training
    Training -.->|"model artifacts"| Model

    %% Click Events
    click Edge "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/hardware/firmware/SmartStrideBLEDevice/SmartStrideBLEDevice.ino"
    click BLE "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/hardware/firmware/bt app sample/Esp32BluetoothApp.ino"
    click API "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/software/backend/main.py"
    click Web "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/software/backend/example.html"
    click Training "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/software/training/algo1.ipynb"
    click Mobile "https://github.com/hirak214/smartstride-tredmill_accessory/blob/main/mobile-app/README.md"

    %% Styles
    classDef hardware fill:#E0F7FA,stroke:#006064,color:#006064
    classDef comm fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef api fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef ml fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef db fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef client fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
