# rishi138/kinetic architecture

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

- Interactive diagram: https://gitdiagram.com/rishi138/kinetic
- Repository: https://github.com/rishi138/kinetic
- Video tour (about a minute): https://gitdiagram.com/rishi138/kinetic/video

## Overview

Kinetic analyzes a live camera feed for ACL-rehabilitation movement quality, then streams annotated video and metrics to a browser dashboard. The sampled runtime captures pose landmarks, smooths them, computes knee deviation, and publishes severity and session-trend data; the UI renders the live feed, metric bars, and trend charts. The README also documents hip drop, trunk lean, LSI, and longitudinal compensation tracking, but the sampled analysis code shows only valgus/varus and in-session history, so those broader capabilities are shown as documented scope rather than confirmed runtime wiring.

Main entry points: [`src/kinetic_cv/main_cv.py`](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/main_cv.py) (Pose analysis loop), [`src/react_front/src/App.jsx`](https://github.com/rishi138/kinetic/blob/main/src/react_front/src/App.jsx) (Dashboard state and layout), [`src/server.py`](https://github.com/rishi138/kinetic/blob/main/src/server.py) (WebSocket relay), [`src/kinetic_cv/pose_landmarker_heavy.task`](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/pose_landmarker_heavy.task) (Pose model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Movement analysis"]
  node_cv_runtime["Pose analysis loop<br/>[main_cv.py]"]
  node_pose_model["Pose model"]
  node_pose_engine["MediaPipe Pose"]
  node_filters["Landmark smoothing<br/>[CustomKalman.py]"]
  node_knee_metric["Knee deviation<br/>[detection_funcs.py]"]
end

subgraph group_transport["Live transport"]
  node_server["WebSocket relay<br/>[server.py]"]
end

subgraph group_dashboard["Clinician dashboard"]
  node_app["Dashboard state and layout<br/>[App.jsx]"]
  node_severity["Severity bars<br/>[SeverityBar.jsx]"]
  node_trend["Session trend chart<br/>[TrendChart.jsx]"]
end

subgraph group_documented["Documented metrics"]
  node_additional_metrics["Other rehab metrics"]
  node_longitudinal["Cross-session trends"]
end

node_camera(("Camera / patient"))
node_browser(("Dashboard viewer"))

node_camera -->|"provides frames"| node_cv_runtime
node_cv_runtime -->|"detects pose"| node_pose_engine
node_pose_model -->|"model asset"| node_pose_engine
node_cv_runtime -->|"smooths landmarks"| node_filters
node_cv_runtime -->|"calculates deviation"| node_knee_metric
node_cv_runtime -->|"sends video and metrics"| node_server
node_server -->|"broadcasts streams"| node_app
node_browser -->|"views dashboard"| node_app
node_app -->|"renders severity"| node_severity
node_app -->|"renders session trend"| node_trend

click node_cv_runtime "https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/main_cv.py"
click node_pose_model "https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/pose_landmarker_heavy.task"
click node_filters "https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/CustomKalman.py"
click node_knee_metric "https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/detection_funcs.py"
click node_server "https://github.com/rishi138/kinetic/blob/main/src/server.py"
click node_app "https://github.com/rishi138/kinetic/blob/main/src/react_front/src/App.jsx"
click node_severity "https://github.com/rishi138/kinetic/blob/main/src/react_front/src/SeverityBar.jsx"
click node_trend "https://github.com/rishi138/kinetic/blob/main/src/react_front/src/TrendChart.jsx"
click node_additional_metrics "https://github.com/rishi138/kinetic/tree/main/src/kinetic_cv"
click node_longitudinal "https://github.com/rishi138/kinetic/tree/main/src/kinetic_cv"

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_cv_runtime,node_pose_model,node_pose_engine,node_filters,node_knee_metric,node_browser toneBlue
class node_server toneAmber
class node_app,node_severity,node_trend toneMint
class node_additional_metrics,node_longitudinal toneRose
class node_camera toneIndigo
```

## Components

### Movement analysis

- [Pose analysis loop](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/main_cv.py): `src/kinetic_cv/main_cv.py`
- [Pose model](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/pose_landmarker_heavy.task): `src/kinetic_cv/pose_landmarker_heavy.task`
- **MediaPipe Pose**
- [Landmark smoothing](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/CustomKalman.py): `src/kinetic_cv/CustomKalman.py`
- [Knee deviation](https://github.com/rishi138/kinetic/blob/main/src/kinetic_cv/detection_funcs.py): `src/kinetic_cv/detection_funcs.py`

### Live transport

- [WebSocket relay](https://github.com/rishi138/kinetic/blob/main/src/server.py): `src/server.py`

### Clinician dashboard

- [Dashboard state and layout](https://github.com/rishi138/kinetic/blob/main/src/react_front/src/App.jsx): `src/react_front/src/App.jsx`
- [Severity bars](https://github.com/rishi138/kinetic/blob/main/src/react_front/src/SeverityBar.jsx): `src/react_front/src/SeverityBar.jsx`
- [Session trend chart](https://github.com/rishi138/kinetic/blob/main/src/react_front/src/TrendChart.jsx): `src/react_front/src/TrendChart.jsx`

### Documented metrics

- [Other rehab metrics](https://github.com/rishi138/kinetic/tree/main/src/kinetic_cv): `src/kinetic_cv`
- [Cross-session trends](https://github.com/rishi138/kinetic/tree/main/src/kinetic_cv): `src/kinetic_cv`

### Other components

- **Camera / patient**
- **Dashboard viewer**

## Connections

- Camera / patient → Pose analysis loop: provides frames
- Pose analysis loop → MediaPipe Pose: detects pose
- Pose model → MediaPipe Pose: model asset
- Pose analysis loop → Landmark smoothing: smooths landmarks
- Pose analysis loop → Knee deviation: calculates deviation
- Pose analysis loop → WebSocket relay: sends video and metrics
- WebSocket relay → Dashboard state and layout: broadcasts streams
- Dashboard viewer → Dashboard state and layout: views dashboard
- Dashboard state and layout → Severity bars: renders severity
- Dashboard state and layout → Session trend chart: renders session trend