# naitikshah1008/live-sports-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/naitikshah1008/live-sports-intelligence
- Repository: https://github.com/naitikshah1008/live-sports-intelligence

## Overview

Live Sports Intelligence processes recorded video or a locally captured screen to detect scoreboard changes, smooth noisy readings into score events, stream events through Kafka, and generate timestamp-refined highlight clips. Spring Boot exposes match, run, event, highlight, and dashboard APIs backed by PostgreSQL; the React dashboard presents scores, timelines, and playable clips. The README also documents Prometheus/Grafana monitoring. Some subsystem links below rely on README architecture statements because their implementation was not sampled; source-level edges are limited to shown calls or indexed references.

Main entry points: [`backend-api/src/main/java/com/naitik/backendapi/repository`](https://github.com/naitikshah1008/live-sports-intelligence/tree/main/backend-api/src/main/java/com/naitik/backendapi/repository) (JPA repositories and entities), [`video-ingestion/main.py`](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py) (Offline pipeline), [`backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java`](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java) (Highlight service), [`video-ingestion/digit_classifier.py`](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/digit_classifier.py) (Digit classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Video input"]
  node_offline_pipeline["Offline pipeline<br/>[main.py]"]
  node_live_monitor["Live monitor"]
end

subgraph group_vision["Detection and clips"]
  node_scoreboard_detection["Scoreboard detection<br/>[main.py]"]
  node_digit_reader["Digit classifier"]
  node_smoothing_events["Score smoothing<br/>[main.py]"]
  node_highlight_generator["Highlight generation<br/>[main.py]"]
  node_digit_training["Digit classifier training"]
end

subgraph group_backend["Backend services"]
  node_kafka["Kafka"]
  node_backend_api["Spring Boot API"]
  node_score_consumer["Score event consumer"]
  node_score_events["Score event service"]
  node_highlights["Highlight service"]
  node_pipeline_runs["Pipeline run service"]
  node_match_service["Match service"]
  node_persistence[("JPA repositories and entities")]
end

subgraph group_ui["Dashboard and monitoring"]
  node_frontend["React dashboard<br/>[App.jsx]"]
  node_prometheus["Prometheus"]
  node_grafana["Grafana"]
end

node_video_input(("Video or screen"))
node_user(("Dashboard user"))

node_video_input -->|"provides video"| node_offline_pipeline
node_video_input -->|"provides screen"| node_live_monitor
node_offline_pipeline -->|"processes frames"| node_scoreboard_detection
node_live_monitor -->|"detects scoreboard"| node_scoreboard_detection
node_scoreboard_detection -->|"reads digits"| node_digit_reader
node_digit_reader -->|"supplies readings"| node_smoothing_events
node_smoothing_events -->|"publishes events"| node_kafka
node_offline_pipeline -->|"generates clips"| node_highlight_generator
node_kafka -->|"streams events"| node_score_consumer
node_score_consumer -->|"saves events"| node_score_events
node_score_events -->|"uses repository"| node_persistence
node_highlights -->|"uses repositories"| node_persistence
node_highlights -->|"deletes matching event"| node_score_events
node_pipeline_runs -->|"uses repositories"| node_persistence
node_match_service -->|"uses repository"| node_persistence
node_highlight_generator -.->|"registers clips"| node_highlights
node_backend_api -->|"serves dashboard data"| node_frontend
node_user -->|"views results"| node_frontend
node_backend_api -->|"exposes metrics"| node_prometheus
node_prometheus -->|"feeds monitoring"| node_grafana
node_digit_training -.->|"trains classifier"| node_digit_reader

click node_offline_pipeline "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py"
click node_live_monitor "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/live_screen_monitor.py"
click node_scoreboard_detection "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py"
click node_digit_reader "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/digit_classifier.py"
click node_smoothing_events "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py"
click node_highlight_generator "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/highlight-service/main.py"
click node_backend_api "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/BackendApiApplication.java"
click node_score_consumer "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/kafka/ScoreEventConsumer.java"
click node_score_events "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/ScoreEventService.java"
click node_highlights "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java"
click node_pipeline_runs "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/PipelineRunService.java"
click node_match_service "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/SportMatchService.java"
click node_persistence "https://github.com/naitikshah1008/live-sports-intelligence/tree/main/backend-api/src/main/java/com/naitik/backendapi/repository"
click node_frontend "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/frontend/src/App.jsx"
click node_digit_training "https://github.com/naitikshah1008/live-sports-intelligence/blob/main/training/digit-classifier/train_digit_classifier.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_offline_pipeline,node_live_monitor,node_video_input,node_user toneBlue
class node_scoreboard_detection,node_digit_reader,node_smoothing_events,node_highlight_generator,node_digit_training toneAmber
class node_kafka,node_backend_api,node_score_consumer,node_score_events,node_highlights,node_pipeline_runs,node_match_service,node_persistence toneMint
class node_frontend,node_prometheus,node_grafana toneRose
```

## Components

### Video input

- [Offline pipeline](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py): `video-ingestion/main.py`
- [Live monitor](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/live_screen_monitor.py): `video-ingestion/live_screen_monitor.py`

### Detection and clips

- [Scoreboard detection](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py): `video-ingestion/main.py`
- [Digit classifier](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/digit_classifier.py): `video-ingestion/digit_classifier.py`
- [Score smoothing](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/video-ingestion/main.py): `video-ingestion/main.py`
- [Highlight generation](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/highlight-service/main.py): `highlight-service/main.py`
- [Digit classifier training](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/training/digit-classifier/train_digit_classifier.py): `training/digit-classifier/train_digit_classifier.py`

### Backend services

- **Kafka**
- [Spring Boot API](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/BackendApiApplication.java): `backend-api/src/main/java/com/naitik/backendapi/BackendApiApplication.java`
- [Score event consumer](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/kafka/ScoreEventConsumer.java): `backend-api/src/main/java/com/naitik/backendapi/kafka/ScoreEventConsumer.java`
- [Score event service](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/ScoreEventService.java): `backend-api/src/main/java/com/naitik/backendapi/service/ScoreEventService.java`
- [Highlight service](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java): `backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java`
- [Pipeline run service](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/PipelineRunService.java): `backend-api/src/main/java/com/naitik/backendapi/service/PipelineRunService.java`
- [Match service](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/backend-api/src/main/java/com/naitik/backendapi/service/SportMatchService.java): `backend-api/src/main/java/com/naitik/backendapi/service/SportMatchService.java`
- [JPA repositories and entities](https://github.com/naitikshah1008/live-sports-intelligence/tree/main/backend-api/src/main/java/com/naitik/backendapi/repository): `backend-api/src/main/java/com/naitik/backendapi/repository`

### Dashboard and monitoring

- [React dashboard](https://github.com/naitikshah1008/live-sports-intelligence/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- **Prometheus**
- **Grafana**

### Other components

- **Video or screen**
- **Dashboard user**

## Connections

- Video or screen → Offline pipeline: provides video (evidence: `README.md`)
- Video or screen → Live monitor: provides screen (evidence: `README.md`)
- Offline pipeline → Scoreboard detection: processes frames (evidence: `video-ingestion/main.py`)
- Live monitor → Scoreboard detection: detects scoreboard (evidence: `README.md`)
- Scoreboard detection → Digit classifier: reads digits (evidence: `video-ingestion/main.py`)
- Digit classifier → Score smoothing: supplies readings (evidence: `README.md`)
- Score smoothing → Kafka: publishes events (evidence: `README.md`)
- Offline pipeline → Highlight generation: generates clips (evidence: `README.md`)
- Kafka → Score event consumer: streams events (evidence: `README.md`)
- Score event consumer → Score event service: saves events (evidence: `README.md`)
- Score event service → JPA repositories and entities: uses repository (evidence: `backend-api/src/main/java/com/naitik/backendapi/service/ScoreEventService.java`)
- Highlight service → JPA repositories and entities: uses repositories (evidence: `backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java`)
- Highlight service → Score event service: deletes matching event (evidence: `backend-api/src/main/java/com/naitik/backendapi/service/HighlightService.java`)
- Pipeline run service → JPA repositories and entities: uses repositories (evidence: `backend-api/src/main/java/com/naitik/backendapi/service/PipelineRunService.java`)
- Match service → JPA repositories and entities: uses repository (evidence: `backend-api/src/main/java/com/naitik/backendapi/service/SportMatchService.java`)
- Highlight generation → Highlight service: registers clips (evidence: `README.md`)
- Spring Boot API → React dashboard: serves dashboard data (evidence: `README.md`)
- Dashboard user → React dashboard: views results (evidence: `README.md`)
- Spring Boot API → Prometheus: exposes metrics (evidence: `README.md`)
- Prometheus → Grafana: feeds monitoring (evidence: `README.md`)
- Digit classifier training → Digit classifier: trains classifier (evidence: `README.md`)