# erwinea/player-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/erwinea/player-analysis
- Repository: https://github.com/erwinea/player-analysis

## Overview

1. **Repository shape**
   - This is a two-tier application: a **Next.js + TypeScript frontend** at the repo root and a **Python FastAPI backend** under `backend/`.
   - The system is centered on a single workflow: upload a match video, choose a sport and target-player hints, run analysis, and return movement plus sport-specific stats.

2. **Frontend subsystem**
   - `src/app` provides the app shell and dashboard page.
   - The main UI is composed from panels in `src/components`: video upload, sport toggle, calibration modal, analysis panel, heatmap panel, player metrics, and sidebar/navigation.
   - Frontend state and payload shaping live in `src/lib`, especially `api.ts`, `analyzeConfig.ts`, `courtConfig.ts`, `pitchCalibration.ts`, and the type definitions under `src/types`.

3. **Frontend-to-backend boundary**
   - The browser submits a multipart analysis request: a video file plus a `details` JSON payload and optional calibration name.
   - The frontend also uses backend health/status checks before analysis and calibration workflows before submission.
   - This boundary is important: the frontend does not run inference locally; it only collects inputs, triggers requests, and renders the returned results.

4. **Backend entrypoints and API layer**
   - `backend/app/main.py` is the application entrypoint, with `pitch_api.py` as the HTTP-facing API layer.
   - `schemas.py` defines request/response contracts, while `upload_utils.py` and `video_store.py` handle upload validation, temporary storage, and video lifecycle management.
   - `cli.py` provides a non-HTTP entry path for backend operations and local execution.

5. **Core analysis pipeline**
   - `backend/app/pipeline/run.py` orchestrates the end-to-end analysis.
   - The pipeline combines detection, tracking, target locking, coordinate calibration, metric generation, and optional sport-specific event inference.
   - `run.py` is the main composition point; most other pipeline modules are reusable stages or helpers.

6. **Shared vision/tracking primitives**
   - Common subsystems include person detection and tracking (`detector.py`, `tracker.py`, `matcher.py`, `bbox.py`), appearance matching (`reid.py`, `reid_extractor.py`), jersey recognition (`jersey_number.py`, `ocr.py`, `easyocr_shared.py`), and color-based disambiguation (`color.py`).
   - `segmentation.py`, `sam_weights.py`, `mask_rle.py`, and `frame_overlay.py` support optional player masks and visualizations.
   - `pitch_homography.py`, `heatmap.py`, and `movement_stats.py` convert frame-space tracking into real-world movement and location metrics.

7. **Sport-specific branching**
   - The pipeline branches on `details.sport` via `backend/app/pipeline/sports/config.py` and sport helpers.
   - **Football** uses jersey-number locking, optional ReID, and ball-event inference.
   - **Badminton** uses court-side selection plus shirt color to identify the tracked player and avoids football-only logic such as jersey OCR.

8. **Football-specific subsystem**
   - Football logic is concentrated in modules like `jersey_number.py`, `jersey_weights.py`, `reid.py`, `ball_events/`, and `insights.py`.
   - `ball_events` models ball detection and event classification, including possession/timeline logic and event resolution.
   - `scene_cut.py`, `lock_audit.py`, and `target_memory.py` support robustness when the tracked player is briefly occluded or the scene changes.

9. **Badminton-specific subsystem**
   - Badminton logic lives under `backend/app/pipeline/badminton/` and `badminton_stats.py`.
   - Key pieces are shuttle detection, shuttle filtering, and rally tracking, which feed rally counts, durations, and serve/return-style stats.
   - `sports/badminton_utils.py` and `sports/config.py` encode court-specific defaults and sport gating.

10. **Calibration and coordinate system**
   - Calibration is a first-class dependency for metre-based movement and heatmaps.
   - The backend stores and reuses calibration artifacts by name; `pitch_homography.py` resolves image-to-court/pitch mapping, and the frontend has dedicated calibration preview and save flows.
   - Calibration dimensions differ by sport, so the same uploaded video can produce different coordinate mappings depending on whether the analysis is football or badminton.

11. **Model assets and runtime configuration**
   - Large model files are kept in `backend/weights/` and are intentionally gitignored.
   - `weight_paths.py` and environment variables control model locations for jersey classification, ReID, ball detection, shuttle detection, and MobileSAM.
   - `inference_device.py` selects the runtime device, which matters for performance and local deployment behavior.

12. **Outputs and response shape**
   - The backend returns a structured analysis result containing target-player trajectory data, movement stats, heatmap data, warnings, and sport-specific metrics.
   - The frontend renders those results in the dashboard panels and can also show annotated video or overlay-style outputs where available.
   - `insights.py` and the frontend `src/lib/insightsPayload.ts`/`parseInsightSummary.ts` bridge raw pipeline outputs to user-facing summaries.

13. **Tooling, scripts, and QA boundary**
   - `backend/tests/` is extensive and exercises both low-level utilities and full pipeline behavior, including calibration, masks, detection, and sport gating.
   - Frontend quality is covered by Playwright tests under `tests/`, plus GitHub Actions workflows for CI and browser checks.
   - `backend/scripts/` and `backend/tools/` are operational helpers for installing weights, rendering overlays, and debugging model behavior rather than part of the runtime path.

14. **External dependencies that materially shape the architecture**
   - The analysis stack relies on computer-vision models: YOLO-style detectors, MobileSAM segmentation, EasyOCR, and a ReID model checkpoint.
   - Because these models are optional and heavyweight, the architecture is designed to degrade gracefully when weights are missing: analysis still runs, but some metrics or masks may be unavailable.

Main entry points: [`backend/app/pipeline/run.py`](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/run.py) (Pipeline run), [`backend/app/pitch_api.py`](https://github.com/erwinea/player-analysis/blob/main/backend/app/pitch_api.py) (HTTP API), [`src/components/Dashboard.tsx`](https://github.com/erwinea/player-analysis/blob/main/src/components/Dashboard.tsx) (Dashboard), [`src/components/UploadAnalyzePanel.tsx`](https://github.com/erwinea/player-analysis/blob/main/src/components/UploadAnalyzePanel.tsx) (Upload flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_app["App shell<br/>Next.js entry"]
  node_dashboard["Dashboard<br/>UI composition<br/>[Dashboard.tsx]"]
  node_upload_panel["Upload flow<br/>UI workflow"]
  node_calibration_modal["Calibration<br/>UI modal"]
  node_results_panels["Results panels<br/>UI outputs"]
  node_frontend_api["API client<br/>TS client<br/>[api.ts]"]
  node_frontend_config["Request config<br/>TS state<br/>[analyzeConfig.ts]"]
  node_frontend_types["Types<br/>TS contracts<br/>[analysis.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_api["HTTP API<br/>API layer<br/>[pitch_api.py]"]
  node_backend_contracts["Schemas<br/>Contracts<br/>[schemas.py]"]
  node_video_storage["Upload store<br/>I/O layer<br/>[upload_utils.py]"]
  node_pipeline_run["Pipeline run<br/>Orchestrator<br/>[run.py]"]
  node_vision_core["Vision core<br/>Detection & tracking<br/>[detector.py]"]
  node_coord_metrics["Coordinates<br/>Calibration & metrics"]
  node_football_branch["Football branch<br/>Sport-specific logic<br/>[run_events.py]"]
  node_badminton_branch["Badminton branch<br/>Sport-specific logic<br/>[rally_tracker.py]"]
end

subgraph group_ops["Assets & Ops"]
  node_runtime_assets["Weights & runtime<br/>Assets<br/>[weight_paths.py]"]
end

node_src_app -->|"renders"| node_dashboard
node_dashboard -->|"includes"| node_upload_panel
node_dashboard -->|"opens"| node_calibration_modal
node_dashboard -->|"renders"| node_results_panels
node_upload_panel -->|"submits"| node_frontend_api
node_upload_panel -->|"builds"| node_frontend_config
node_upload_panel -->|"uses"| node_frontend_types
node_calibration_modal -->|"writes"| node_frontend_config
node_frontend_api -->|"calls"| node_backend_api
node_backend_main -->|"serves"| node_backend_api
node_backend_api -->|"validates"| node_backend_contracts
node_backend_api -->|"stores"| node_video_storage
node_backend_api -->|"invokes"| node_pipeline_run
node_pipeline_run -->|"uses"| node_vision_core
node_pipeline_run -->|"derives"| node_coord_metrics
node_pipeline_run -->|"branches"| node_football_branch
node_pipeline_run -->|"branches"| node_badminton_branch
node_pipeline_run -->|"depends on"| node_runtime_assets
node_coord_metrics -->|"feeds"| node_results_panels
node_football_branch -->|"feeds"| node_results_panels
node_badminton_branch -->|"feeds"| node_results_panels

click node_src_app "https://github.com/erwinea/player-analysis/tree/main/src/app"
click node_dashboard "https://github.com/erwinea/player-analysis/blob/main/src/components/Dashboard.tsx"
click node_upload_panel "https://github.com/erwinea/player-analysis/blob/main/src/components/UploadAnalyzePanel.tsx"
click node_calibration_modal "https://github.com/erwinea/player-analysis/blob/main/src/components/PitchCalibrationModal.tsx"
click node_results_panels "https://github.com/erwinea/player-analysis/blob/main/src/components/GameplayAnalysisPanel.tsx"
click node_frontend_api "https://github.com/erwinea/player-analysis/blob/main/src/lib/api.ts"
click node_frontend_config "https://github.com/erwinea/player-analysis/blob/main/src/lib/analyzeConfig.ts"
click node_frontend_types "https://github.com/erwinea/player-analysis/blob/main/src/types/analysis.ts"
click node_backend_main "https://github.com/erwinea/player-analysis/blob/main/backend/app/main.py"
click node_backend_api "https://github.com/erwinea/player-analysis/blob/main/backend/app/pitch_api.py"
click node_backend_contracts "https://github.com/erwinea/player-analysis/blob/main/backend/app/schemas.py"
click node_video_storage "https://github.com/erwinea/player-analysis/blob/main/backend/app/upload_utils.py"
click node_pipeline_run "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/run.py"
click node_vision_core "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/detector.py"
click node_coord_metrics "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/pitch_homography.py"
click node_football_branch "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/ball_events/run_events.py"
click node_badminton_branch "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/badminton/rally_tracker.py"
click node_runtime_assets "https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/weight_paths.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_src_app,node_dashboard,node_upload_panel,node_calibration_modal,node_results_panels,node_frontend_api,node_frontend_config,node_frontend_types toneBlue
class node_backend_main,node_backend_api,node_backend_contracts,node_video_storage,node_pipeline_run,node_vision_core,node_coord_metrics,node_football_branch,node_badminton_branch toneAmber
class node_runtime_assets toneMint
```

## Components

### Frontend

Next.js app that collects inputs, calls the backend, and renders analysis results.

- [App shell](https://github.com/erwinea/player-analysis/tree/main/src/app): Next.js entry · Root app shell and page composition for the dashboard experience. · `src/app`
- [Dashboard](https://github.com/erwinea/player-analysis/blob/main/src/components/Dashboard.tsx): UI composition · Main page layout that ties together upload, analysis, and result panels. · `src/components/Dashboard.tsx`
- [Upload flow](https://github.com/erwinea/player-analysis/blob/main/src/components/UploadAnalyzePanel.tsx): UI workflow · Combines video upload, sport selection, and analysis submission controls. · `src/components/UploadAnalyzePanel.tsx`
- [Calibration](https://github.com/erwinea/player-analysis/blob/main/src/components/PitchCalibrationModal.tsx): UI modal · Frontend calibration preview and save flow before analysis submission. · `src/components/PitchCalibrationModal.tsx`
- [Results panels](https://github.com/erwinea/player-analysis/blob/main/src/components/GameplayAnalysisPanel.tsx): UI outputs · Analysis, heatmap, metrics, and sidebar panels that render backend results. · `src/components/GameplayAnalysisPanel.tsx`
- [API client](https://github.com/erwinea/player-analysis/blob/main/src/lib/api.ts): TS client · Browser request layer for health checks, uploads, and analysis submission. · `src/lib/api.ts`
- [Request config](https://github.com/erwinea/player-analysis/blob/main/src/lib/analyzeConfig.ts): TS state · Analysis payload shaping, court/sport config, and calibration helpers. · `src/lib/analyzeConfig.ts`
- [Types](https://github.com/erwinea/player-analysis/blob/main/src/types/analysis.ts): TS contracts · Shared frontend types for analysis, sport selection, and metrics. · `src/types/analysis.ts`

### Backend

FastAPI service plus the analysis pipeline and sport-specific branches.

- [App entry](https://github.com/erwinea/player-analysis/blob/main/backend/app/main.py): FastAPI app · Backend application entrypoint and service bootstrap. · `backend/app/main.py`
- [HTTP API](https://github.com/erwinea/player-analysis/blob/main/backend/app/pitch_api.py): API layer · HTTP-facing endpoints for upload, calibration, and analysis workflows. · `backend/app/pitch_api.py`
- [Schemas](https://github.com/erwinea/player-analysis/blob/main/backend/app/schemas.py): Contracts · Request and response schemas used by the API and pipeline boundary. · `backend/app/schemas.py`
- [Upload store](https://github.com/erwinea/player-analysis/blob/main/backend/app/upload_utils.py): I/O layer · Upload validation and temporary video lifecycle management. · `backend/app/upload_utils.py`
- [Pipeline run](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/run.py): Orchestrator · End-to-end analysis composition point for detection, tracking, calibration, and metrics. · `backend/app/pipeline/run.py`
- [Vision core](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/detector.py): Detection & tracking · Shared detection, tracking, matching, and appearance primitives. · `backend/app/pipeline/detector.py`
- [Coordinates](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/pitch_homography.py): Calibration & metrics · Homography, movement stats, heatmaps, and insight generation. · `backend/app/pipeline/pitch_homography.py`
- [Football branch](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/ball_events/run_events.py): Sport-specific logic · Football-specific jersey locking, ball events, and scene robustness logic. · `backend/app/pipeline/ball_events/run_events.py`
- [Badminton branch](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/badminton/rally_tracker.py): Sport-specific logic · Badminton-specific shuttle and rally analysis plus court defaults. · `backend/app/pipeline/badminton/rally_tracker.py`

### Assets & Ops

Weights, scripts, and workflows that support local execution and CI.

- [Weights & runtime](https://github.com/erwinea/player-analysis/blob/main/backend/app/pipeline/weight_paths.py): Assets · Model weight locations and inference device selection for local/runtime behavior. · `backend/app/pipeline/weight_paths.py`

## Connections

- App shell → Dashboard: renders · The app shell mounts the dashboard page and shared layout.
- Dashboard → Upload flow: includes · Dashboard composes the upload and analysis controls.
- Dashboard → Calibration: opens · Dashboard exposes the calibration flow before submission.
- Dashboard → Results panels: renders · Dashboard displays analysis outputs in dedicated panels.
- Upload flow → API client: submits · Browser sends multipart analysis requests and health checks through the API client.
- Upload flow → Request config: builds · Upload controls shape details JSON and analysis options.
- Upload flow → Types: uses · UI state and payloads are typed against shared analysis models.
- Calibration → Request config: writes · Calibration UI updates the named calibration payload and preview state.
- API client → HTTP API: calls · Frontend requests the backend HTTP analysis and calibration endpoints.
- App entry → HTTP API: serves · Application startup wires the HTTP API layer.
- HTTP API → Schemas: validates · Endpoint inputs and outputs are defined by shared schemas.
- HTTP API → Upload store: stores · Uploads are validated and staged before analysis.
- HTTP API → Pipeline run: invokes · HTTP requests trigger the core analysis pipeline.
- Pipeline run → Vision core: uses · Pipeline orchestrates detection, tracking, and target identification.
- Pipeline run → Coordinates: derives · Pipeline converts tracks into calibration-aware movement and heatmap outputs.
- Pipeline run → Football branch: branches · Football analyses enable jersey locking and ball-event inference.
- Pipeline run → Badminton branch: branches · Badminton analyses enable shuttle and rally tracking.
- Pipeline run → Weights & runtime: depends on · Pipeline behavior depends on configured model paths and device selection.
- Coordinates → Results panels: feeds · Backend metrics are rendered in the frontend result panels.
- Football branch → Results panels: feeds · Sport-specific football outputs surface in the UI.
- Badminton branch → Results panels: feeds · Sport-specific badminton outputs surface in the UI.
