# emmetsurmeli/track-sprinting-ai architecture

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

- Interactive diagram: https://gitdiagram.com/emmetsurmeli/track-sprinting-ai
- Repository: https://github.com/emmetsurmeli/track-sprinting-ai

## Overview

Track Sprint AI is a local Streamlit sprint-video review application. An athlete sets up a profile, uploads and trims a recording, then reviews locally computed pose and movement measurements. The app supports human-reviewed contact timing and landing posture, and sends eligible measurements, athlete context, and selected research evidence to OpenAI for constrained coaching—not the video. Results can be inspected, revisited in a dated training calendar, compared across eligible sessions, and exported. The graph follows documented capabilities and sampled orchestration; some UI-to-module wiring and unsampled implementation details are intentionally left out.

Main entry points: [`app.py`](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/app.py) (App orchestrator), [`src/track_sprint/pipeline.py`](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/pipeline.py) (Analysis pipeline), [`src/track_sprint/coaching.py`](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/coaching.py) (Coaching generation), [`src/track_sprint/contact_ui.py`](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/contact_ui.py) (Contact review UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Analysis workflow"]
  node_video["Video handling<br/>[video.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_pose["Pose tracking<br/>[pose.py]"]
  node_metrics["Motion metrics<br/>[metrics.py]"]
  node_render["Video rendering<br/>[render.py]"]
end

subgraph group_evidence["Review evidence"]
  node_movement["Bilateral movement<br/>[movement.py]"]
  node_contacts["Contact timing<br/>[contacts.py]"]
  node_posture["Landing posture<br/>[posture.py]"]
end

subgraph group_coaching["Coaching"]
  node_coaching["Coaching generation<br/>[coaching.py]"]
  node_research["Research library<br/>[evidence.json]"]
  node_activities["Practice activities<br/>[activities.json]"]
end

subgraph group_history["History and output"]
  node_history[("Training history<br/>[history.py]")]
  node_cache["Analysis cache<br/>[analysis_cache.py]"]
  node_artifacts["Analysis artifacts<br/>[artifacts.py]"]
end

subgraph group_interface["User interface"]
  node_app["App orchestrator<br/>[app.py]"]
  node_profile["Profile setup<br/>[profile_setup.py]"]
  node_contact_ui["Contact review UI<br/>[contact_ui.py]"]
  node_frame_viewer["Frame viewer<br/>[frame_viewer.py]"]
  node_calendar["Calendar UI<br/>[calendar_ui.py]"]
  node_charts["Charts<br/>[charts.py]"]
  node_export["Artifact export<br/>[app.py]"]
end

node_athlete(("Athlete"))
node_openai{{"OpenAI API"}}

node_athlete -->|"uses"| node_app
node_app -->|"shows setup"| node_profile
node_app -->|"inspects upload"| node_video
node_app -->|"starts analysis"| node_pipeline
node_pipeline -->|"tracks frames"| node_pose
node_pipeline -->|"calculates angles"| node_metrics
node_pipeline -->|"writes results"| node_artifacts
node_pipeline -->|"creates annotated video"| node_render
node_app -->|"checks reuse"| node_cache
node_app -->|"offers event review"| node_contact_ui
node_contact_ui -->|"scrubs frames"| node_frame_viewer
node_contact_ui -->|"saves marks"| node_contacts
node_app -->|"derives movement evidence"| node_movement
node_app -->|"derives reviewed posture"| node_posture
node_app -->|"requests report"| node_coaching
node_coaching -->|"retrieves evidence"| node_research
node_coaching -->|"selects activities"| node_activities
node_coaching -->|"requests explanation"| node_openai
node_app -->|"records analysis"| node_history
node_app -->|"shows training log"| node_calendar
node_calendar -->|"reads sessions"| node_history
node_calendar -->|"plots progress"| node_charts
node_app -->|"packages results"| node_export
node_export -->|"reads derived files"| node_artifacts

click node_app "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/app.py"
click node_profile "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/profile_setup.py"
click node_video "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/video.py"
click node_pipeline "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/pipeline.py"
click node_pose "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/pose.py"
click node_metrics "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/metrics.py"
click node_movement "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/movement.py"
click node_contact_ui "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/contact_ui.py"
click node_contacts "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/contacts.py"
click node_posture "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/posture.py"
click node_frame_viewer "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/frame_viewer.py"
click node_coaching "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/coaching.py"
click node_research "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/data/evidence.json"
click node_activities "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/data/activities.json"
click node_calendar "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/calendar_ui.py"
click node_history "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/history.py"
click node_cache "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/analysis_cache.py"
click node_render "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/render.py"
click node_charts "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/charts.py"
click node_artifacts "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/artifacts.py"
click node_export "https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/app.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_video,node_pipeline,node_pose,node_metrics,node_render toneBlue
class node_movement,node_contacts,node_posture toneAmber
class node_coaching,node_research,node_activities,node_openai toneMint
class node_history,node_cache,node_artifacts toneRose
class node_app,node_profile,node_contact_ui,node_frame_viewer,node_calendar,node_charts,node_export,node_athlete toneIndigo
```

## Components

### Analysis workflow

- [Video handling](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/video.py): `src/track_sprint/video.py`
- [Analysis pipeline](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/pipeline.py): `src/track_sprint/pipeline.py`
- [Pose tracking](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/pose.py): `src/track_sprint/pose.py`
- [Motion metrics](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/metrics.py): `src/track_sprint/metrics.py`
- [Video rendering](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/render.py): `src/track_sprint/render.py`

### Review evidence

- [Bilateral movement](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/movement.py): `src/track_sprint/movement.py`
- [Contact timing](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/contacts.py): `src/track_sprint/contacts.py`
- [Landing posture](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/posture.py): `src/track_sprint/posture.py`

### Coaching

- [Coaching generation](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/coaching.py): `src/track_sprint/coaching.py`
- [Research library](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/data/evidence.json): `src/track_sprint/data/evidence.json`
- [Practice activities](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/data/activities.json): `src/track_sprint/data/activities.json`

### History and output

- [Training history](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/history.py): `src/track_sprint/history.py`
- [Analysis cache](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/analysis_cache.py): `src/track_sprint/analysis_cache.py`
- [Analysis artifacts](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/artifacts.py): `src/track_sprint/artifacts.py`

### User interface

- [App orchestrator](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/app.py): `app.py`
- [Profile setup](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/profile_setup.py): `src/track_sprint/profile_setup.py`
- [Contact review UI](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/contact_ui.py): `src/track_sprint/contact_ui.py`
- [Frame viewer](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/frame_viewer.py): `src/track_sprint/frame_viewer.py`
- [Calendar UI](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/calendar_ui.py): `src/track_sprint/calendar_ui.py`
- [Charts](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/src/track_sprint/charts.py): `src/track_sprint/charts.py`
- [Artifact export](https://github.com/emmetsurmeli/track-sprinting-ai/blob/main/app.py): `app.py`

### Other components

- **Athlete**
- **OpenAI API**

## Connections

- Athlete → App orchestrator: uses
- App orchestrator → Profile setup: shows setup
- App orchestrator → Video handling: inspects upload
- App orchestrator → Analysis pipeline: starts analysis
- Analysis pipeline → Pose tracking: tracks frames
- Analysis pipeline → Motion metrics: calculates angles
- Analysis pipeline → Analysis artifacts: writes results
- Analysis pipeline → Video rendering: creates annotated video
- App orchestrator → Analysis cache: checks reuse
- App orchestrator → Contact review UI: offers event review
- Contact review UI → Frame viewer: scrubs frames
- Contact review UI → Contact timing: saves marks
- App orchestrator → Bilateral movement: derives movement evidence
- App orchestrator → Landing posture: derives reviewed posture
- App orchestrator → Coaching generation: requests report
- Coaching generation → Research library: retrieves evidence
- Coaching generation → Practice activities: selects activities
- Coaching generation → OpenAI API: requests explanation
- App orchestrator → Training history: records analysis
- App orchestrator → Calendar UI: shows training log
- Calendar UI → Training history: reads sessions
- Calendar UI → Charts: plots progress
- App orchestrator → Artifact export: packages results
- Artifact export → Analysis artifacts: reads derived files