# leohq1/formcheck architecture

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

- Interactive diagram: https://gitdiagram.com/leohq1/formcheck
- Repository: https://github.com/leohq1/formcheck

## Overview

FormCheck is an asynchronous badminton-clip coaching application: a player submits a clip, the API stores and queues it, a worker analyzes movement, and the browser presents progress and coaching results. The graph includes documented video, pose, biomechanics, rules, and retrieval/generation stages. Some runtime wiring—especially from the durable worker into the provisional analysis pipeline and coaching subsystem—is not established by the sampled excerpts, so those connections are omitted or marked unverified.

Main entry points: [`services/worker/analysis/formcheck_analysis/pipeline.py`](https://github.com/leohq1/formcheck/blob/main/services/worker/analysis/formcheck_analysis/pipeline.py) (Analysis pipeline), [`services/formcheck/worker/tasks.py`](https://github.com/leohq1/formcheck/blob/main/services/formcheck/worker/tasks.py) (Analysis worker), [`services/formcheck/api/routes.py`](https://github.com/leohq1/formcheck/blob/main/services/formcheck/api/routes.py) (HTTP API), [`packages/rules/formcheck_rules/engine.py`](https://github.com/leohq1/formcheck/blob/main/packages/rules/formcheck_rules/engine.py) (Technique rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_upload["Clip upload<br/>[UploadPage.tsx]"]
  node_results["Analysis results<br/>[AnalysisPage.tsx]"]
  node_api_client["API client<br/>[httpClient.ts]"]
end

subgraph group_service["API and jobs"]
  node_api["HTTP API<br/>[routes.py]"]
  node_storage[("Object storage<br/>[storage.py]")]
  node_queue["Job queue<br/>[broker.py]"]
  node_db[("Analysis records<br/>[db.py]")]
  node_worker["Analysis worker<br/>[tasks.py]"]
end

subgraph group_analysis["Movement analysis"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_video["Video preparation<br/>[normalization.py]"]
  node_pose["Pose estimation"]
  node_quality["Quality checks<br/>[quality.py]"]
  node_segmentation["Stroke segmentation<br/>[segmentation.py]"]
  node_phases["Phase estimation<br/>[phases.py]"]
  node_features["Biomechanics features<br/>[arm_extension.py]"]
  node_biomech_config["Biomechanics config<br/>[config.py]"]
  node_rules["Technique rules<br/>[engine.py]"]
end

subgraph group_coaching["Coaching feedback"]
  node_rag["Coaching retrieval<br/>[retrieval.py]"]
  node_generation["Feedback generation<br/>[generator.py]"]
end

node_player(("Player"))

node_player -->|"uses"| node_webapp
node_webapp -->|"presents"| node_upload
node_upload -->|"submits clip"| node_api_client
node_results -->|"requests results"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"stores uploads"| node_storage
node_api -->|"enqueues jobs"| node_queue
node_api -->|"reads and writes"| node_db
node_queue -.->|"dispatches jobs"| node_worker
node_worker -->|"persists results"| node_db
node_worker -.->|"reads clip"| node_storage
node_worker -.->|"invokes analysis"| node_pipeline
node_pipeline -.->|"runs preparation"| node_video
node_pipeline -.->|"runs estimation"| node_pose
node_pipeline -.->|"assesses quality"| node_quality
node_pipeline -.->|"segments stroke"| node_segmentation
node_pipeline -.->|"estimates phases"| node_phases
node_pipeline -->|"extracts features"| node_features
node_pipeline -->|"evaluates rules"| node_rules
node_features -->|"uses configuration"| node_biomech_config
node_rules -->|"evaluates values"| node_features
node_rules -.->|"supplies findings"| node_rag
node_rag -.->|"provides passages"| node_generation
node_generation -.->|"returns coaching"| node_worker
node_worker -->|"serves result"| node_results

click node_webapp "https://github.com/leohq1/formcheck/blob/main/apps/web/src/App.tsx"
click node_upload "https://github.com/leohq1/formcheck/blob/main/apps/web/src/pages/UploadPage.tsx"
click node_results "https://github.com/leohq1/formcheck/blob/main/apps/web/src/pages/AnalysisPage.tsx"
click node_api_client "https://github.com/leohq1/formcheck/blob/main/apps/web/src/api/httpClient.ts"
click node_api "https://github.com/leohq1/formcheck/blob/main/services/formcheck/api/routes.py"
click node_storage "https://github.com/leohq1/formcheck/blob/main/services/formcheck/storage.py"
click node_queue "https://github.com/leohq1/formcheck/blob/main/services/formcheck/worker/broker.py"
click node_db "https://github.com/leohq1/formcheck/blob/main/services/formcheck/db.py"
click node_worker "https://github.com/leohq1/formcheck/blob/main/services/formcheck/worker/tasks.py"
click node_pipeline "https://github.com/leohq1/formcheck/blob/main/services/worker/analysis/formcheck_analysis/pipeline.py"
click node_video "https://github.com/leohq1/formcheck/blob/main/packages/video/formcheck_video/normalization.py"
click node_pose "https://github.com/leohq1/formcheck/blob/main/packages/pose/formcheck_pose/mediapipe_estimator.py"
click node_quality "https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/quality.py"
click node_segmentation "https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/segmentation.py"
click node_phases "https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/phases.py"
click node_features "https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/features/arm_extension.py"
click node_biomech_config "https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/config.py"
click node_rules "https://github.com/leohq1/formcheck/blob/main/packages/rules/formcheck_rules/engine.py"
click node_rag "https://github.com/leohq1/formcheck/blob/main/packages/rag/src/formcheck_rag/retrieval.py"
click node_generation "https://github.com/leohq1/formcheck/blob/main/packages/rag/src/formcheck_rag/generator.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_webapp,node_upload,node_results,node_api_client toneBlue
class node_api,node_storage,node_queue,node_db,node_worker toneAmber
class node_pipeline,node_video,node_pose,node_quality,node_segmentation,node_phases,node_features,node_biomech_config,node_rules toneMint
class node_rag,node_generation toneRose
class node_player toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/leohq1/formcheck/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Clip upload](https://github.com/leohq1/formcheck/blob/main/apps/web/src/pages/UploadPage.tsx): `apps/web/src/pages/UploadPage.tsx`
- [Analysis results](https://github.com/leohq1/formcheck/blob/main/apps/web/src/pages/AnalysisPage.tsx): `apps/web/src/pages/AnalysisPage.tsx`
- [API client](https://github.com/leohq1/formcheck/blob/main/apps/web/src/api/httpClient.ts): `apps/web/src/api/httpClient.ts`

### API and jobs

- [HTTP API](https://github.com/leohq1/formcheck/blob/main/services/formcheck/api/routes.py): `services/formcheck/api/routes.py`
- [Object storage](https://github.com/leohq1/formcheck/blob/main/services/formcheck/storage.py): `services/formcheck/storage.py`
- [Job queue](https://github.com/leohq1/formcheck/blob/main/services/formcheck/worker/broker.py): `services/formcheck/worker/broker.py`
- [Analysis records](https://github.com/leohq1/formcheck/blob/main/services/formcheck/db.py): `services/formcheck/db.py`
- [Analysis worker](https://github.com/leohq1/formcheck/blob/main/services/formcheck/worker/tasks.py): `services/formcheck/worker/tasks.py`

### Movement analysis

- [Analysis pipeline](https://github.com/leohq1/formcheck/blob/main/services/worker/analysis/formcheck_analysis/pipeline.py): `services/worker/analysis/formcheck_analysis/pipeline.py`
- [Video preparation](https://github.com/leohq1/formcheck/blob/main/packages/video/formcheck_video/normalization.py): `packages/video/formcheck_video/normalization.py`
- [Pose estimation](https://github.com/leohq1/formcheck/blob/main/packages/pose/formcheck_pose/mediapipe_estimator.py): `packages/pose/formcheck_pose/mediapipe_estimator.py`
- [Quality checks](https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/quality.py): `packages/biomechanics/formcheck_biomechanics/quality.py`
- [Stroke segmentation](https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/segmentation.py): `packages/biomechanics/formcheck_biomechanics/segmentation.py`
- [Phase estimation](https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/phases.py): `packages/biomechanics/formcheck_biomechanics/phases.py`
- [Biomechanics features](https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/features/arm_extension.py): `packages/biomechanics/formcheck_biomechanics/features/arm_extension.py`
- [Biomechanics config](https://github.com/leohq1/formcheck/blob/main/packages/biomechanics/formcheck_biomechanics/config.py): `packages/biomechanics/formcheck_biomechanics/config.py`
- [Technique rules](https://github.com/leohq1/formcheck/blob/main/packages/rules/formcheck_rules/engine.py): `packages/rules/formcheck_rules/engine.py`

### Coaching feedback

- [Coaching retrieval](https://github.com/leohq1/formcheck/blob/main/packages/rag/src/formcheck_rag/retrieval.py): `packages/rag/src/formcheck_rag/retrieval.py`
- [Feedback generation](https://github.com/leohq1/formcheck/blob/main/packages/rag/src/formcheck_rag/generator.py): `packages/rag/src/formcheck_rag/generator.py`

### Other components

- **Player**

## Connections

- Player → Web application: uses (evidence: `README.md`)
- Web application → Clip upload: presents (evidence: `README.md`)
- Clip upload → API client: submits clip (evidence: `README.md`)
- Analysis results → API client: requests results (evidence: `README.md`)
- API client → HTTP API: calls API (evidence: `README.md`)
- HTTP API → Object storage: stores uploads (evidence: `services/formcheck/api/routes.py`)
- HTTP API → Job queue: enqueues jobs (evidence: `services/formcheck/api/main.py`)
- HTTP API → Analysis records: reads and writes (evidence: `services/formcheck/api/routes.py`)
- Job queue → Analysis worker: dispatches jobs (evidence: `services/formcheck/worker/tasks.py`)
- Analysis worker → Analysis records: persists results (evidence: `services/formcheck/worker/tasks.py`)
- Analysis worker → Object storage: reads clip (evidence: `services/formcheck/worker/tasks.py`)
- Analysis worker → Analysis pipeline: invokes analysis
- Analysis pipeline → Video preparation: runs preparation
- Analysis pipeline → Pose estimation: runs estimation
- Analysis pipeline → Quality checks: assesses quality
- Analysis pipeline → Stroke segmentation: segments stroke
- Analysis pipeline → Phase estimation: estimates phases
- Analysis pipeline → Biomechanics features: extracts features (evidence: `services/worker/analysis/formcheck_analysis/pipeline.py`)
- Analysis pipeline → Technique rules: evaluates rules (evidence: `services/worker/analysis/formcheck_analysis/pipeline.py`)
- Biomechanics features → Biomechanics config: uses configuration (evidence: `packages/biomechanics/formcheck_biomechanics/features/arm_extension.py`)
- Technique rules → Biomechanics features: evaluates values (evidence: `packages/rules/formcheck_rules/engine.py`)
- Technique rules → Coaching retrieval: supplies findings
- Coaching retrieval → Feedback generation: provides passages
- Feedback generation → Analysis worker: returns coaching
- Analysis worker → Analysis results: serves result (evidence: `README.md`)
