# mjdmahasneh/sport-analysis-with-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mjdmahasneh/sport-analysis-with-ai
- Repository: https://github.com/mjdmahasneh/sport-analysis-with-ai

## Overview

SportVision is a Streamlit sports-analysis app with separate image and video workflows. Uploaded images receive pose/person detection and team separation, then OCR and optional Groq commentary; video frames receive tracked detections, team assignments, motion trails and trajectory overlays, and are encoded for playback/download. The graph follows documented capabilities and sampled calls; the detailed detector internals are combined because they share detector.py. Video UI orchestration is documented but its call site was not included in the excerpt.

Main entry points: [`detector.py`](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/detector.py) (Detection and team analysis), [`app.py`](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/app.py) (Upload and results UI), [`config.py`](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/config.py) (Analysis settings), [`ocr_reader.py`](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/ocr_reader.py) (Text recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Streamlit experience"]
  node_app["Upload and results UI<br/>[app.py]"]
  node_config["Analysis settings<br/>[config.py]"]
end

subgraph group_vision["Vision analysis"]
  node_vision_pipeline["Detection and team analysis<br/>[detector.py]"]
end

subgraph group_video["Video analytics"]
  node_team_tracking["Stable team assignments<br/>[utils.py]"]
  node_motion_helpers["Trails and projections<br/>[utils.py]"]
  node_video_output["H.264 video output<br/>[detector.py]"]
end

subgraph group_insights["Text insights"]
  node_ocr["Text recognition<br/>[ocr_reader.py]"]
  node_commentary["Commentary generation<br/>[commentary.py]"]
end

node_user(("Sports analyst"))
node_groq["Groq LLM API"]
node_easyocr_engine["EasyOCR engine"]
node_ultralytics["YOLO and ByteTrack"]
node_video_upload["Video upload"]
node_image_upload["Image upload"]

node_user -->|"uploads media"| node_app
node_app -->|"runs image analysis"| node_vision_pipeline
node_app -->|"requests text scan"| node_ocr
node_app -->|"requests commentary"| node_commentary
node_vision_pipeline -.->|"runs pose and tracking"| node_ultralytics
node_vision_pipeline -->|"updates video teams"| node_team_tracking
node_vision_pipeline -->|"draws trails and projections"| node_motion_helpers
node_vision_pipeline -->|"encodes annotated frames"| node_video_output
node_ocr -->|"recognizes text"| node_easyocr_engine
node_commentary -->|"requests generated text"| node_groq
node_config -->|"sets thresholds"| node_vision_pipeline
node_config -->|"sets OCR options"| node_ocr
node_config -->|"sets model options"| node_commentary
node_image_upload -->|"supplies image"| node_app
node_video_upload -->|"supplies clip"| node_app

click node_app "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/app.py"
click node_config "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/config.py"
click node_vision_pipeline "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/detector.py"
click node_team_tracking "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/utils.py"
click node_motion_helpers "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/utils.py"
click node_video_output "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/detector.py"
click node_ocr "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/ocr_reader.py"
click node_commentary "https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/commentary.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 toneBlue
class node_vision_pipeline toneAmber
class node_team_tracking,node_motion_helpers,node_video_output,node_groq toneMint
class node_ocr,node_commentary toneRose
class node_user,node_easyocr_engine,node_ultralytics,node_video_upload,node_image_upload toneIndigo
```

## Components

### Streamlit experience

- [Upload and results UI](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/app.py): `app.py`
- [Analysis settings](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/config.py): `config.py`

### Vision analysis

- [Detection and team analysis](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/detector.py): `detector.py`

### Video analytics

- [Stable team assignments](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/utils.py): `utils.py`
- [Trails and projections](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/utils.py): `utils.py`
- [H.264 video output](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/detector.py): `detector.py`

### Text insights

- [Text recognition](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/ocr_reader.py): `ocr_reader.py`
- [Commentary generation](https://github.com/mjdmahasneh/sport-analysis-with-ai/blob/master/commentary.py): `commentary.py`

### Other components

- **Sports analyst**
- **Groq LLM API**
- **EasyOCR engine**
- **YOLO and ByteTrack**
- **Video upload**
- **Image upload**

## Connections

- Sports analyst → Upload and results UI: uploads media (evidence: `README.md`)
- Upload and results UI → Detection and team analysis: runs image analysis (evidence: `app.py`)
- Upload and results UI → Text recognition: requests text scan (evidence: `app.py`)
- Upload and results UI → Commentary generation: requests commentary (evidence: `app.py`)
- Detection and team analysis → YOLO and ByteTrack: runs pose and tracking (evidence: `README.md`)
- Detection and team analysis → Stable team assignments: updates video teams (evidence: `detector.py`)
- Detection and team analysis → Trails and projections: draws trails and projections (evidence: `detector.py`)
- Detection and team analysis → H.264 video output: encodes annotated frames (evidence: `detector.py`)
- Text recognition → EasyOCR engine: recognizes text (evidence: `ocr_reader.py`)
- Commentary generation → Groq LLM API: requests generated text (evidence: `commentary.py`)
- Analysis settings → Detection and team analysis: sets thresholds (evidence: `detector.py`)
- Analysis settings → Text recognition: sets OCR options (evidence: `ocr_reader.py`)
- Analysis settings → Commentary generation: sets model options (evidence: `commentary.py`)
- Image upload → Upload and results UI: supplies image (evidence: `README.md`)
- Video upload → Upload and results UI: supplies clip (evidence: `README.md`)
