# shivasankari27/physiobot architecture

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

- Interactive diagram: https://gitdiagram.com/shivasankari27/physiobot
- Repository: https://github.com/shivasankari27/physiobot

## Overview

1. **Purpose and runtime shape**
   - This is a single-process Python computer-vision application for rehab coaching.
   - `app.py` is the orchestration entry point: it parses CLI flags, opens the camera, runs the processing loop, renders the overlay, and saves session data on exit.

2. **Top-level data flow**
   - The main loop is a pipeline: camera frame → pose estimation → joint/angle features → scoring and safety rules → session trend tracking → on-screen overlay.
   - Safety warnings are treated as a higher-priority output than normal quality feedback.

3. **Pose acquisition subsystem**
   - `pose/estimator.py` is the boundary to the pose-tracking runtime, using MediaPipe skeletal landmarks.
   - Its responsibility is to turn raw frames into structured landmark data for downstream analysis, not to score movement quality itself.

4. **Feature extraction subsystem**
   - `pose/features.py` computes biomechanical angles from landmarks and handles left/right arm selection.
   - It also supports auto-selection of the more visible arm, which matters because the rest of the system consumes a single “active arm” view.

5. **Exercise configuration boundary**
   - `config.py` centralizes exercise definitions and thresholds in `EXERCISES`.
   - Each exercise configuration defines ideal angles, danger cutoffs, scoring weights, and whether elbow scoring uses extension or flexion semantics.
   - This keeps movement logic data-driven rather than hard-coded across the app.

6. **Feedback and safety rules**
   - `feedback/rules.py` is the scoring and decision engine.
   - It converts angle features into a 0–100 form score, generates user-facing feedback text, and detects danger zones that trigger immediate safety warnings.
   - This subsystem is the policy boundary between raw kinematics and rehab guidance.

7. **Session analytics and persistence**
   - `feedback/session.py` tracks scores over time, computes rolling-mean trend state, and persists the session at shutdown.
   - Session records are saved as JSON under `data/sessions/`, capturing exercise type, timestamps, score history, average score, and trend classification.
   - This module is the stateful boundary for longitudinal analysis.

8. **UI presentation**
   - `ui/overlay.py` is responsible for rendering the unified on-screen status layer.
   - It displays the current score, feedback message, trend, active exercise, tracked arm, and the red safety warning when applicable.
   - The overlay is presentation-only; it does not own decision logic.

9. **Operational modes and controls**
   - The app supports two exercise modes: `arm_raise` and `bicep_curl`.
   - CLI flags select exercise, camera index, and arm side (`left`, `right`, or `auto`), which feed directly into the pose/feature and rules pipeline.
   - `q` is the exit control that also triggers session persistence.

10. **Testing and architecture coverage**
   - `tests/test_features.py`, `tests/test_rules.py`, and `tests/test_session.py` map directly to the three core logic areas: kinematic math, scoring/safety rules, and session behavior.
   - The tests indicate that the repo’s important boundaries are pure logic modules around a thin real-time application shell.

11. **Key architectural separation**
   - The repo cleanly separates acquisition, computation, policy, presentation, and persistence.
   - That separation is important for diagramming: the camera and MediaPipe runtime sit at one edge, while JSON session storage sits at the other, with scoring and overlay rendering in the middle.

Main entry points: [`app.py`](https://github.com/shivasankari27/physiobot/blob/main/app.py) (App), [`feedback/rules.py`](https://github.com/shivasankari27/physiobot/blob/main/feedback/rules.py) (Rules), [`feedback/session.py`](https://github.com/shivasankari27/physiobot/blob/main/feedback/session.py) (Session), [`pose/features.py`](https://github.com/shivasankari27/physiobot/blob/main/pose/features.py) (Features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App<br/>entrypoint loop<br/>[app.py]"]
  node_config["Exercises<br/>exercise config<br/>[config.py]"]
  node_camera(("Camera<br/>video source"))
  node_exercise_mode(("Exercise Mode<br/>runtime setting"))
  node_arm_side(("Arm Side<br/>runtime setting"))
end

subgraph group_pose["Pose"]
  node_estimator["Estimator<br/>mediapipe boundary<br/>[estimator.py]"]
  node_features["Features<br/>angle extraction<br/>[features.py]"]
end

subgraph group_feedback["Feedback"]
  node_rules["Rules<br/>scoring policy<br/>[rules.py]"]
  node_session[("Session<br/>trend state<br/>[session.py]")]
  node_sessions_data[("Session Data<br/>json store")]
end

subgraph group_ui["UI"]
  node_overlay["Overlay<br/>presentation layer<br/>[overlay.py]"]
end

subgraph group_tests["Tests"]
  node_tests_features["Feature Tests<br/>unit tests<br/>[test_features.py]"]
  node_tests_rules["Rules Tests<br/>unit tests<br/>[test_rules.py]"]
  node_tests_session["Session Tests<br/>unit tests<br/>[test_session.py]"]
end

node_app -->|"opens"| node_camera
node_app -->|"selects"| node_exercise_mode
node_app -->|"selects"| node_arm_side
node_app -->|"feeds frames"| node_estimator
node_estimator -->|"landmarks"| node_features
node_features -->|"angles"| node_rules
node_config -->|"thresholds"| node_rules
node_config -->|"semantics"| node_features
node_rules -->|"scores"| node_session
node_rules -->|"feedback"| node_overlay
node_session -->|"trend"| node_overlay
node_rules -->|"warning"| node_overlay
node_session -->|"persists"| node_sessions_data
node_app -->|"renders"| node_overlay
node_app -->|"finalizes"| node_session
node_tests_features -.->|"covers"| node_features
node_tests_rules -.->|"covers"| node_rules
node_tests_session -.->|"covers"| node_session

click node_app "https://github.com/shivasankari27/physiobot/blob/main/app.py"
click node_config "https://github.com/shivasankari27/physiobot/blob/main/config.py"
click node_estimator "https://github.com/shivasankari27/physiobot/blob/main/pose/estimator.py"
click node_features "https://github.com/shivasankari27/physiobot/blob/main/pose/features.py"
click node_rules "https://github.com/shivasankari27/physiobot/blob/main/feedback/rules.py"
click node_session "https://github.com/shivasankari27/physiobot/blob/main/feedback/session.py"
click node_overlay "https://github.com/shivasankari27/physiobot/blob/main/ui/overlay.py"
click node_tests_features "https://github.com/shivasankari27/physiobot/blob/main/tests/test_features.py"
click node_tests_rules "https://github.com/shivasankari27/physiobot/blob/main/tests/test_rules.py"
click node_tests_session "https://github.com/shivasankari27/physiobot/blob/main/tests/test_session.py"

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_app,node_config,node_camera,node_exercise_mode,node_arm_side toneBlue
class node_estimator,node_features toneAmber
class node_rules,node_session,node_sessions_data toneMint
class node_overlay toneRose
class node_tests_features,node_tests_rules,node_tests_session toneIndigo
```

## Components

### Runtime

CLI entrypoint and live processing loop

- [App](https://github.com/shivasankari27/physiobot/blob/main/app.py): entrypoint loop · Parses CLI flags, opens the camera, runs the real-time processing loop, renders overlays, and saves the session on exit. · `app.py`
- [Exercises](https://github.com/shivasankari27/physiobot/blob/main/config.py): exercise config · Central exercise definitions and thresholds for arm_raise and bicep_curl, including target angles, danger cutoffs, weights, and elbow semantics. · `config.py`
- **Camera**: video source · Live frame input selected by camera index.
- **Exercise Mode**: runtime setting · Selected rehab mode, either arm_raise or bicep_curl.
- **Arm Side**: runtime setting · Selected arm input, left, right, or auto.

### Pose

Frame acquisition and landmark feature extraction

- [Estimator](https://github.com/shivasankari27/physiobot/blob/main/pose/estimator.py): mediapipe boundary · Converts raw frames into structured skeletal landmarks using the pose-tracking runtime. · `pose/estimator.py`
- [Features](https://github.com/shivasankari27/physiobot/blob/main/pose/features.py): angle extraction · Computes biomechanical angles from landmarks and handles left/right or auto-selected active arm. · `pose/features.py`

### Feedback

Scoring, safety, and session tracking

- [Rules](https://github.com/shivasankari27/physiobot/blob/main/feedback/rules.py): scoring policy · Maps angle features to form scores, generates user feedback, and detects danger zones for safety warnings. · `feedback/rules.py`
- [Session](https://github.com/shivasankari27/physiobot/blob/main/feedback/session.py): trend state · Tracks score history, computes rolling trends, and persists session records as JSON at shutdown. · `feedback/session.py`
- **Session Data**: json store · Saved session records under data/sessions/.

### UI

On-screen overlay rendering

- [Overlay](https://github.com/shivasankari27/physiobot/blob/main/ui/overlay.py): presentation layer · Renders the on-screen status layer with score, feedback, trend, active exercise, tracked arm, and safety warning. · `ui/overlay.py`

### Tests

Core logic coverage

- [Feature Tests](https://github.com/shivasankari27/physiobot/blob/main/tests/test_features.py): unit tests · Covers kinematic math and arm selection behavior. · `tests/test_features.py`
- [Rules Tests](https://github.com/shivasankari27/physiobot/blob/main/tests/test_rules.py): unit tests · Covers scoring, feedback, and danger detection behavior. · `tests/test_rules.py`
- [Session Tests](https://github.com/shivasankari27/physiobot/blob/main/tests/test_session.py): unit tests · Covers session tracking, trend classification, and persistence behavior. · `tests/test_session.py`

## Connections

- App → Camera: opens · Initializes the chosen camera source.
- App → Exercise Mode: selects · CLI selects the active exercise.
- App → Arm Side: selects · CLI selects left/right/auto arm mode.
- App → Estimator: feeds frames · Processing loop sends frames into pose estimation.
- Estimator → Features: landmarks · Extracted landmarks flow into feature computation.
- Features → Rules: angles · Angle features are evaluated by scoring and safety policy.
- Exercises → Rules: thresholds · Exercise definitions drive scoring and danger cutoffs.
- Exercises → Features: semantics · Exercise setup informs active arm handling and elbow interpretation.
- Rules → Session: scores · Form scores and feedback are recorded over time.
- Rules → Overlay: feedback · Normal guidance text and score are rendered in the overlay.
- Session → Overlay: trend · Rolling trend state is displayed to the user.
- Rules → Overlay: warning · Safety warnings take precedence in the visual status layer.
- Session → Session Data: persists · Shutdown writes session JSON records to disk.
- App → Overlay: renders · The main loop composes the final on-screen status layer.
- App → Session: finalizes · Exit control triggers session persistence and cleanup.
- Feature Tests → Features: covers · Validates feature extraction and arm selection logic.
- Rules Tests → Rules: covers · Validates scoring, feedback, and safety decisions.
- Session Tests → Session: covers · Validates trend tracking and persistence behavior.