# sathish-create/fitcoach_ai_web architecture

> Architecture diagram of the GitHub repository sathish-create/fitcoach_ai_web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sathish-create/fitcoach_ai_web
- Repository: https://github.com/sathish-create/fitcoach_ai_web

## Overview

#### Purpose and entry points
This repository is a fitness/coaching application with a static browser frontend and a Python backend for pose-based exercise analysis. Primary entry points are `backend/main.py` for the service and `frontend/index.html` for the client. Deployment configuration is in `render.yaml`.

#### Backend analysis service
`backend/main.py` hosts the backend API/runtime and delegates exercise-form analysis into the engine. The packaged pose model `backend/pose_landmarker.task` is a material runtime asset, indicating local pose-landmark inference rather than a remote vision API. Python dependencies are defined in `backend/requirements.txt`.

#### Pose processing boundary
`backend/utils/pose_utils.py` is the boundary between raw pose-landmarker output and normalized/derived pose data consumed by analysis rules. `backend/engine/analyzer.py` coordinates analysis: it likely selects applicable exercise/body-region rules, evaluates landmarks, and returns coaching or validation results to the API layer.

#### Rule-based form evaluation
The engine is organized as modular rule groups under `backend/engine/rules/`. `backend/engine/rules/base.py` and `backend/engine/rules/abs.py` establish shared and abdominal-specific evaluation behavior; other groups encode body-region or exercise-form logic, including `backend/engine/rules/arms.py`, `backend/engine/rules/back.py`, `backend/engine/rules/chest.py`, `backend/engine/rules/full_body.py`, `backend/engine/rules/legs.py`, `backend/engine/rules/shoulders.py`, and `backend/engine/rules/triceps.py`. This keeps pose inference separate from domain-specific coaching criteria.

#### Frontend application surfaces
The frontend is a multi-page static application. Workout and coaching flows are represented by `frontend/workout.html` and `frontend/coach.html`; discovery and content pages include `frontend/exercises.html`, `frontend/library.html`, and `frontend/gyms.html`. Shared client behavior is concentrated in `frontend/js/app.js`, with gym-specific behavior in `frontend/js/gyms.js` and visual landing behavior in `frontend/js/landing-effects.js`.

#### Content, identity, and persistence
Exercise content is locally represented in `frontend/exercises.json`. Authentication and client-side Supabase integration are isolated in `frontend/js/supabase-auth.js` and `frontend/js/supabase-config.js`. The database contract is captured in `supabase_schema.sql`, making Supabase the primary external backend service for account and application persistence rather than the Python pose-analysis service.

#### Operational boundaries
The frontend is browser-hosted HTML/CSS/JavaScript, while the backend requires a Python runtime plus the local pose model. `render.yaml` is the deployment/infrastructure boundary. `backend/error_log.txt` and `backend/verify_logic.py` suggest local operational diagnostics and rule-validation support, but the production architecture centers on browser UI → Supabase for app data/auth and browser/UI → Python service for pose/form analysis.

Main entry points: [`backend/engine/analyzer.py`](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/analyzer.py) (Form analyzer), [`frontend/js/app.js`](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/app.js) (Shared app behavior), [`frontend/workout.html`](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/workout.html) (Workout & coaching pages), [`backend/main.py`](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/main.py) (Analysis API runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser frontend"]
  node_browser(("Browser user<br/>client runtime"))
  node_frontend_pages["Workout &amp; coaching pages<br/>static HTML<br/>[workout.html]"]
  node_content_pages["Discovery pages<br/>static HTML<br/>[exercises.html]"]
  node_app_js["Shared app behavior<br/>browser JavaScript<br/>[app.js]"]
  node_gym_js["Gym behavior<br/>browser JavaScript<br/>[gyms.js]"]
  node_landing_js["Landing effects<br/>browser JavaScript<br/>[landing-effects.js]"]
  node_exercise_content["Exercise catalog<br/>local JSON content<br/>[exercises.json]"]
  node_supabase_client["Supabase client<br/>browser auth integration<br/>[supabase-auth.js]"]
end

subgraph group_analysis["Pose analysis service"]
  node_analysis_api["Analysis API runtime<br/>Python service<br/>[main.py]"]
  node_pose_model{{"Pose landmarker model<br/>local ML model"}}
  node_pose_utils["Pose normalization<br/>pose processing boundary<br/>[pose_utils.py]"]
  node_analyzer["Form analyzer<br/>analysis orchestrator<br/>[analyzer.py]"]
  node_base_abs_rules["Base &amp; abs rules<br/>rule modules<br/>[base.py]"]
  node_upper_rules["Upper-body rules<br/>rule modules<br/>[arms.py]"]
  node_lower_full_rules["Lower &amp; full-body rules<br/>rule modules<br/>[legs.py]"]
end

subgraph group_supabase["Supabase"]
  node_supabase_auth["Auth service<br/>Supabase identity"]
  node_supabase_db[("Application database<br/>Supabase persistence")]
end

node_deployment["Deployment config<br/>infrastructure definition<br/>[render.yaml]"]

node_browser -->|"uses"| node_frontend_pages
node_browser -->|"browses"| node_content_pages
node_frontend_pages -->|"loads"| node_app_js
node_content_pages -->|"loads"| node_app_js
node_content_pages -->|"uses for gyms"| node_gym_js
node_app_js -.->|"supports landing UI"| node_landing_js
node_app_js -->|"reads"| node_exercise_content
node_app_js -->|"uses"| node_supabase_client
node_supabase_client -->|"authenticates with"| node_supabase_auth
node_supabase_client -->|"reads and writes"| node_supabase_db
node_frontend_pages -->|"submits pose/form analysis"| node_analysis_api
node_analysis_api -->|"runs local inference"| node_pose_model
node_pose_model -->|"produces landmarks"| node_pose_utils
node_pose_utils -->|"normalizes pose data"| node_analyzer
node_analyzer -->|"evaluates"| node_base_abs_rules
node_analyzer -->|"evaluates"| node_upper_rules
node_analyzer -->|"evaluates"| node_lower_full_rules
node_analyzer -->|"returns coaching result"| node_analysis_api
node_deployment -.->|"deploys static frontend"| node_frontend_pages
node_deployment -.->|"deploys service"| node_analysis_api

click node_frontend_pages "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/workout.html"
click node_content_pages "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/exercises.html"
click node_app_js "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/app.js"
click node_gym_js "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/gyms.js"
click node_landing_js "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/landing-effects.js"
click node_exercise_content "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/exercises.json"
click node_supabase_client "https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/supabase-auth.js"
click node_analysis_api "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/main.py"
click node_pose_model "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/pose_landmarker.task"
click node_pose_utils "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/utils/pose_utils.py"
click node_analyzer "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/analyzer.py"
click node_base_abs_rules "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/base.py"
click node_upper_rules "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/arms.py"
click node_lower_full_rules "https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/legs.py"
click node_supabase_db "https://github.com/sathish-create/fitcoach_ai_web/blob/main/supabase_schema.sql"
click node_deployment "https://github.com/sathish-create/fitcoach_ai_web/blob/main/render.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_frontend_pages,node_content_pages,node_app_js,node_gym_js,node_landing_js,node_exercise_content,node_supabase_client toneBlue
class node_analysis_api,node_pose_model,node_pose_utils,node_analyzer,node_base_abs_rules,node_upper_rules,node_lower_full_rules toneAmber
class node_supabase_auth,node_supabase_db toneMint
class node_deployment toneNeutral
```

## Components

### Browser frontend

Static multi-page fitness application.

- **Browser user**: client runtime
- [Workout & coaching pages](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/workout.html): static HTML · Interactive exercise and coaching surfaces. · `frontend/workout.html`
- [Discovery pages](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/exercises.html): static HTML · Exercises, library, and gyms pages. · `frontend/exercises.html`
- [Shared app behavior](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/app.js): browser JavaScript · `frontend/js/app.js`
- [Gym behavior](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/gyms.js): browser JavaScript · `frontend/js/gyms.js`
- [Landing effects](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/landing-effects.js): browser JavaScript · `frontend/js/landing-effects.js`
- [Exercise catalog](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/exercises.json): local JSON content · `frontend/exercises.json`
- [Supabase client](https://github.com/sathish-create/fitcoach_ai_web/blob/main/frontend/js/supabase-auth.js): browser auth integration · `frontend/js/supabase-auth.js`

### Pose analysis service

Python runtime for local pose-based coaching.

- [Analysis API runtime](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/main.py): Python service · Receives pose/form analysis requests. · `backend/main.py`
- [Pose landmarker model](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/pose_landmarker.task): local ML model · `backend/pose_landmarker.task`
- [Pose normalization](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/utils/pose_utils.py): pose processing boundary · Converts model output into analysis-ready pose data. · `backend/utils/pose_utils.py`
- [Form analyzer](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/analyzer.py): analysis orchestrator · Selects and evaluates exercise-form rules. · `backend/engine/analyzer.py`
- [Base & abs rules](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/base.py): rule modules · `backend/engine/rules/base.py`
- [Upper-body rules](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/arms.py): rule modules · Arms, back, chest, shoulders, and triceps criteria. · `backend/engine/rules/arms.py`
- [Lower & full-body rules](https://github.com/sathish-create/fitcoach_ai_web/blob/main/backend/engine/rules/legs.py): rule modules · Leg and full-body criteria. · `backend/engine/rules/legs.py`

### Supabase

External identity and application persistence.

- **Auth service**: Supabase identity
- [Application database](https://github.com/sathish-create/fitcoach_ai_web/blob/main/supabase_schema.sql): Supabase persistence · Schema contract defines account and application data. · `supabase_schema.sql`

### Other components

- [Deployment config](https://github.com/sathish-create/fitcoach_ai_web/blob/main/render.yaml): infrastructure definition · Defines hosting/deployment boundary. · `render.yaml`

## Connections

- Browser user → Workout & coaching pages: uses
- Browser user → Discovery pages: browses
- Workout & coaching pages → Shared app behavior: loads
- Discovery pages → Shared app behavior: loads
- Discovery pages → Gym behavior: uses for gyms
- Shared app behavior → Landing effects: supports landing UI
- Shared app behavior → Exercise catalog: reads
- Shared app behavior → Supabase client: uses
- Supabase client → Auth service: authenticates with
- Supabase client → Application database: reads and writes
- Workout & coaching pages → Analysis API runtime: submits pose/form analysis
- Analysis API runtime → Pose landmarker model: runs local inference
- Pose landmarker model → Pose normalization: produces landmarks
- Pose normalization → Form analyzer: normalizes pose data
- Form analyzer → Base & abs rules: evaluates
- Form analyzer → Upper-body rules: evaluates
- Form analyzer → Lower & full-body rules: evaluates
- Form analyzer → Analysis API runtime: returns coaching result
- Deployment config → Workout & coaching pages: deploys static frontend
- Deployment config → Analysis API runtime: deploys service