# smartyash11/ai-fitness-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/smartyash11/ai-fitness-analyzer
- Repository: https://github.com/smartyash11/ai-fitness-analyzer

## Overview

##### Project type and purpose
- This is a full-stack fitness analytics application.
- Frontend: Next.js + React + Tailwind UI running on Vercel
- Backend/Processing: Python modules for computer vision (MediaPipe, OpenCV, NumPy) exposed either as serverless functions or a microservice.

##### File structure
- Top level:
- Dockerfile, setup.sh, requirements.txt → deployment and environment setup for Python service
- process_frame.py, thresholds.py, utils.py → core CV/ML logic
- 🏠️_Demo.py → Streamlit-based demo version (local)
- Sample output videos → examples of processed output
- Missing front-end folder in repo implies the Next.js code lives in another repo or will be added under `/frontend`.

##### Key insights from README
- Real-time pose detection, form analysis, rep counting, feedback visuals
- Frontend captures camera frames, backend performs pose estimation & scoring
- Original demo runs locally via Streamlit; production uses Next.js + serverless Python

##### Main components
a. Client (Browser / Mobile)
b. Frontend (Next.js)
c. API Layer / Serverless Functions
d. CV Processing Service (Python):
– process_frame.py
– thresholds.py
– utils.py
– MediaPipe, OpenCV, NumPy libraries
e. Deployment infrastructure:
– Vercel (frontend)
– Container or serverless (backend) via Dockerfile / setup.sh

##### Relationships and data flows
1. User grants camera access → Browser
2. Frontend streams frames over WebSocket/HTTP POST → API Layer
3. API Layer invokes Python service
4. Python service loads frame → process_frame.py
- Detects landmarks via MediaPipe
- Computes angles & thresholds via thresholds.py
- Applies helpers in utils.py
5. Returns JSON (angles, rep count, feedback flags) and/or annotated image
6. Frontend renders live overlays and updates rep counters

##### Architectural patterns & design principles
- Separation of concerns: UI vs. processing
- Microservice/serverless for compute-heavy CV
- Stateless functions for scalability
- Dockerized environment for reproducible deployment

##### Essential details to capture
- API endpoints or WebSocket channels between Next.js and the Python service
- The 3 main Python modules (process_frame, thresholds, utils) as sub-components
- External CV libraries as dependencies
- Demo mode (Streamlit) as an alternate local-run path via 🏠️_Demo.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Camera((Camera Device)):::external
    Browser["Browser/Client"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        NextJS["Next.js Frontend"]:::frontend
        API["API Layer<br/>(Serverless Functions)"]:::frontend
        Vercel((Vercel)):::deploy
    end

    %% Backend Layer
    subgraph "Backend Layer"
        CVService["Python CV Service"]:::backend
        process_frame["process_frame.py"]:::backend
        thresholds["thresholds.py"]:::backend
        utils["utils.py"]:::backend
        Docker((Docker Container)):::deploy
        Setup["setup.sh"]:::backend
        Req["requirements.txt"]:::backend
    end

    %% Dependencies
    Mediapipe["MediaPipe"]:::lib
    OpenCV["OpenCV"]:::lib
    NumPy["NumPy"]:::lib

    %% Demo Mode
    Demo["🏠️_Demo.py"]:::demo

    %% Sample Outputs
    subgraph "Sample Output Media"
        output_live["output_live.flv"]:::media
        output_sample["output_sample.mp4"]:::media
    end

    %% Data Flows
    Camera -->|"grant camera access"| Browser
    Browser -->|"streams frames"| NextJS
    NextJS -->|"HTTP POST / WebSocket"| API
    API -->|"invoke"| CVService
    CVService -->|loads frame & runs| process_frame
    CVService -->|computes angles| thresholds
    CVService -->|helper functions| utils
    CVService -->|uses| Mediapipe
    CVService -->|uses| OpenCV
    CVService -->|uses| NumPy
    CVService -->|"returns JSON / annotated image"| NextJS
    NextJS --> Browser

    %% Deployment Connections
    NextJS --> Vercel
    CVService --> Docker
    Docker --> Setup
    Docker --> Req

    %% Demo Flow
    Browser -->|"local demo"| Demo
    Demo --> process_frame
    Demo --> thresholds
    Demo --> utils

    %% Sample Outputs Flow
    CVService --> output_live
    CVService --> output_sample

    %% Click Events
    click process_frame "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/process_frame.py"
    click thresholds "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/thresholds.py"
    click utils "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/utils.py"
    click Demo "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/🏠️_Demo.py"
    click Docker "https://github.com/smartyash11/ai-fitness-analyzer/tree/main/Dockerfile"
    click Setup "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/setup.sh"
    click Req "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/requirements.txt"
    click output_live "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/output_live.flv"
    click output_sample "https://github.com/smartyash11/ai-fitness-analyzer/blob/main/output_sample.mp4"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#333,stroke-width:1px
    classDef lib fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef deploy fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef media fill:#ffdead,stroke:#333,stroke-width:1px
    classDef demo fill:#fafad2,stroke:#333,stroke-width:1px
```
