# mariuscnn/sports-video-coach architecture

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

- Interactive diagram: https://gitdiagram.com/mariuscnn/sports-video-coach
- Repository: https://github.com/mariuscnn/sports-video-coach

## Overview

sports-video-coach is a local, agent-assisted sports-film coaching tool, not a hosted app. A user supplies video and coaching context; the resumable CLI prepares review material, pauses for the agent’s observations and words, then produces a multilingual coaching page, spoken report and explained video. Generic review, fitness analysis and basketball game review are distinct product paths. The README documents these capabilities; sampled excerpts expose core orchestration and fitness validation, while basketball implementation details are only partly sampled, so uncertain internal links are omitted.

Main entry points: [`src/sports_video_coach/pipeline.py`](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/pipeline.py) (Resumable pipeline), [`src/hoop_tape_miner/coach_review.py`](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_review.py) (Basketball review), [`src/svc_fitness/unit.py`](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/unit.py) (Fitness session), [`src/sports_video_coach/film.py`](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/film.py) (Explained video)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core coaching workflow"]
  node_cli["CLI<br/>[cli.py]"]
  node_pipeline["Resumable pipeline<br/>[pipeline.py]"]
  node_plugin["Sport plugins<br/>[plugin.py]"]
  node_media["Media tools<br/>[media.py]"]
end

subgraph group_generic["Generic coaching outputs"]
  node_generic_unit["Generic review<br/>[unit.py]"]
  node_clips["Clip extraction<br/>[clips.py]"]
  node_lessons["Evidence lessons<br/>[lessons.py]"]
  node_narrate["Report narration<br/>[narrate.py]"]
  node_film["Explained video<br/>[film.py]"]
  node_html["Coaching page<br/>[render_html.py]"]
  node_languages["Language registry<br/>[langs.py]"]
end

subgraph group_fitness["Fitness plugin"]
  node_fitness_plugin["Fitness plugin<br/>[plugin.py]"]
  node_fitness_unit["Fitness session<br/>[unit.py]"]
  node_exercise_library["Exercise library<br/>[library.py]"]
  node_pose["Pose analysis<br/>[pose.py]"]
  node_reps["Rep metrics<br/>[reps.py]"]
  node_fitness_page["Fitness report page<br/>[page.py]"]
end

subgraph group_basketball["Basketball review"]
  node_basket_review["Basketball review<br/>[coach_review.py]"]
  node_coach_eval["Coach evaluation<br/>[coach_eval.py]"]
  node_coach_schema["Review schema<br/>[coach_schema.py]"]
  node_progress["Review progress<br/>[review_progress.py]"]
  node_court["Court model<br/>[court.py]"]
  node_possessions["Possession analysis<br/>[possessions.py]"]
  node_team_pages["Team and player pages<br/>[coach_summary.py]"]
  node_basket_features["Basketball analytics<br/>[coach_insights.py]"]
end

node_user(("Player or coach"))
node_result["Coaching deliverables"]

node_user -->|"submits video"| node_cli
node_cli -->|"starts run"| node_pipeline
node_pipeline -->|"loads plugin"| node_plugin
node_pipeline -->|"uses media tools"| node_media
node_pipeline -->|"runs stages"| node_generic_unit
node_pipeline -->|"runs clips stage"| node_clips
node_pipeline -->|"runs narration"| node_narrate
node_pipeline -->|"runs film stage"| node_film
node_pipeline -->|"renders page"| node_html
node_film -->|"uses clips"| node_clips
node_film -->|"processes video"| node_media
node_film -->|"uses narration"| node_narrate
node_html -->|"renders clip markers"| node_clips
node_html -->|"localizes page"| node_languages
node_pipeline -->|"uses lessons"| node_lessons
node_pipeline -->|"produces reports"| node_result
node_user -->|"chooses fitness"| node_fitness_plugin
node_fitness_plugin -->|"provides session unit"| node_fitness_unit
node_fitness_unit -->|"validates exercises"| node_exercise_library
node_fitness_unit -->|"runs pose stage"| node_pose
node_fitness_unit -->|"runs rep stage"| node_reps
node_fitness_unit -->|"uses report page"| node_fitness_page
node_fitness_plugin -->|"adds strength metrics"| node_result
node_user -->|"chooses basketball"| node_basket_review
node_basket_review -->|"uses evaluation"| node_coach_eval
node_basket_review -->|"checks review data"| node_coach_schema
node_basket_review -->|"tracks sheet coverage"| node_progress
node_basket_review -->|"uses court model"| node_court
node_basket_review -.->|"uses possessions"| node_possessions
node_basket_review -.->|"builds team pages"| node_team_pages
node_basket_review -.->|"summarizes coaching insights"| node_basket_features
node_basket_review -->|"produces game review"| node_result

click node_cli "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/cli.py"
click node_pipeline "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/pipeline.py"
click node_plugin "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/plugin.py"
click node_media "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/media.py"
click node_generic_unit "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/plugins/generic/unit.py"
click node_clips "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/clips.py"
click node_lessons "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/lessons.py"
click node_narrate "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/narrate.py"
click node_film "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/film.py"
click node_html "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/render_html.py"
click node_languages "https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/langs.py"
click node_fitness_plugin "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/plugin.py"
click node_fitness_unit "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/unit.py"
click node_exercise_library "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/library.py"
click node_pose "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/pose.py"
click node_reps "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/reps.py"
click node_fitness_page "https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/page.py"
click node_basket_review "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_review.py"
click node_coach_eval "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_eval.py"
click node_coach_schema "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_schema.py"
click node_progress "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/review_progress.py"
click node_court "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/court.py"
click node_possessions "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/possessions.py"
click node_team_pages "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_summary.py"
click node_basket_features "https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_insights.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_cli,node_pipeline,node_plugin,node_media toneBlue
class node_generic_unit,node_clips,node_lessons,node_narrate,node_film,node_html,node_languages toneAmber
class node_fitness_plugin,node_fitness_unit,node_exercise_library,node_pose,node_reps,node_fitness_page toneMint
class node_basket_review,node_coach_eval,node_coach_schema,node_progress,node_court,node_possessions,node_team_pages,node_basket_features toneRose
class node_user,node_result toneIndigo
```

## Components

### Core coaching workflow

- [CLI](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/cli.py): `src/sports_video_coach/cli.py`
- [Resumable pipeline](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/pipeline.py): `src/sports_video_coach/pipeline.py`
- [Sport plugins](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/plugin.py): `src/sports_video_coach/plugin.py`
- [Media tools](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/media.py): `src/sports_video_coach/media.py`

### Generic coaching outputs

- [Generic review](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/plugins/generic/unit.py): `src/sports_video_coach/plugins/generic/unit.py`
- [Clip extraction](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/clips.py): `src/sports_video_coach/clips.py`
- [Evidence lessons](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/lessons.py): `src/sports_video_coach/lessons.py`
- [Report narration](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/narrate.py): `src/sports_video_coach/narrate.py`
- [Explained video](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/film.py): `src/sports_video_coach/film.py`
- [Coaching page](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/render_html.py): `src/sports_video_coach/render_html.py`
- [Language registry](https://github.com/mariuscnn/sports-video-coach/blob/master/src/sports_video_coach/langs.py): `src/sports_video_coach/langs.py`

### Fitness plugin

- [Fitness plugin](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/plugin.py): `src/svc_fitness/plugin.py`
- [Fitness session](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/unit.py): `src/svc_fitness/unit.py`
- [Exercise library](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/library.py): `src/svc_fitness/library.py`
- [Pose analysis](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/pose.py): `src/svc_fitness/pose.py`
- [Rep metrics](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/reps.py): `src/svc_fitness/reps.py`
- [Fitness report page](https://github.com/mariuscnn/sports-video-coach/blob/master/src/svc_fitness/page.py): `src/svc_fitness/page.py`

### Basketball review

- [Basketball review](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_review.py): `src/hoop_tape_miner/coach_review.py`
- [Coach evaluation](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_eval.py): `src/hoop_tape_miner/coach_eval.py`
- [Review schema](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_schema.py): `src/hoop_tape_miner/coach_schema.py`
- [Review progress](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/review_progress.py): `src/hoop_tape_miner/review_progress.py`
- [Court model](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/court.py): `src/hoop_tape_miner/court.py`
- [Possession analysis](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/possessions.py): `src/hoop_tape_miner/possessions.py`
- [Team and player pages](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_summary.py): `src/hoop_tape_miner/coach_summary.py`
- [Basketball analytics](https://github.com/mariuscnn/sports-video-coach/blob/master/src/hoop_tape_miner/coach_insights.py): `src/hoop_tape_miner/coach_insights.py`

### Other components

- **Player or coach**
- **Coaching deliverables**

## Connections

- Player or coach → CLI: submits video
- CLI → Resumable pipeline: starts run (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Sport plugins: loads plugin (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Media tools: uses media tools (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Generic review: runs stages (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Clip extraction: runs clips stage (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Report narration: runs narration (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Explained video: runs film stage (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Coaching page: renders page (evidence: `src/sports_video_coach/pipeline.py`)
- Explained video → Clip extraction: uses clips (evidence: `src/sports_video_coach/film.py`)
- Explained video → Media tools: processes video (evidence: `src/sports_video_coach/film.py`)
- Explained video → Report narration: uses narration (evidence: `src/sports_video_coach/film.py`)
- Coaching page → Clip extraction: renders clip markers (evidence: `src/sports_video_coach/render_html.py`)
- Coaching page → Language registry: localizes page (evidence: `src/sports_video_coach/render_html.py`)
- Resumable pipeline → Evidence lessons: uses lessons (evidence: `src/sports_video_coach/pipeline.py`)
- Resumable pipeline → Coaching deliverables: produces reports
- Player or coach → Fitness plugin: chooses fitness
- Fitness plugin → Fitness session: provides session unit (evidence: `src/svc_fitness/plugin.py`)
- Fitness session → Exercise library: validates exercises (evidence: `src/svc_fitness/unit.py`)
- Fitness session → Pose analysis: runs pose stage (evidence: `src/svc_fitness/unit.py`)
- Fitness session → Rep metrics: runs rep stage (evidence: `src/svc_fitness/unit.py`)
- Fitness session → Fitness report page: uses report page (evidence: `src/svc_fitness/unit.py`)
- Fitness plugin → Coaching deliverables: adds strength metrics
- Player or coach → Basketball review: chooses basketball
- Basketball review → Coach evaluation: uses evaluation (evidence: `src/hoop_tape_miner/coach_review.py`)
- Basketball review → Review schema: checks review data (evidence: `src/hoop_tape_miner/coach_review.py`)
- Basketball review → Review progress: tracks sheet coverage (evidence: `src/hoop_tape_miner/coach_review.py`)
- Basketball review → Court model: uses court model (evidence: `src/hoop_tape_miner/coach_review.py`)
- Basketball review → Possession analysis: uses possessions
- Basketball review → Team and player pages: builds team pages
- Basketball review → Basketball analytics: summarizes coaching insights
- Basketball review → Coaching deliverables: produces game review
