# eyalshub/live-video-quality-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/eyalshub/live-video-quality-monitor
- Repository: https://github.com/eyalshub/live-video-quality-monitor

## Overview

Live Video Quality Monitor captures webcam frames and analyzes them entirely in the browser, producing per-second quality metrics, a Good/Poor verdict, live insights and a 30-second view. The monitor batches numeric samples to a FastAPI service, which validates and re-checks verdicts before storing sessions in Postgres; the History screen retrieves stored sessions for replay. Video stays in the browser. The README documents the end-to-end flow; source-index references establish several internal module links, but unsampled UI and service details limit finer call attribution.

Main entry points: [`frontend/src/session/monitor.ts`](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/monitor.ts) (Session monitor), [`frontend/src/ui/App.tsx`](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/App.tsx) (App and routing), [`backend/app/services/sessions.py`](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/services/sessions.py) (Session lifecycle), [`frontend/src/capture/frameLoop.ts`](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/frameLoop.ts) (Frame loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Browser capture"]
  node_camera_access["Camera access<br/>[camera.ts]"]
  node_frame_loop["Frame loop<br/>[frameLoop.ts]"]
  node_face_detector["Face detection<br/>[faceDetector.ts]"]
  node_frame_analysis["Frame analysis<br/>[frameAnalyzer.ts]"]
end

subgraph group_analysis["Metrics and session"]
  node_frame_metrics["Frame metrics<br/>[frame.ts]"]
  node_face_filter["Face filter<br/>[faceFilter.ts]"]
  node_verdict["Quality verdict<br/>[verdict.ts]"]
  node_insights["Extra insights<br/>[insights.ts]"]
  node_sample_aggregator["Sample aggregation<br/>[aggregator.ts]"]
  node_insight_aggregator["Insight aggregation"]
  node_monitor["Session monitor<br/>[monitor.ts]"]
  node_outbox["Sample outbox<br/>[outbox.ts]"]
end

subgraph group_frontend["Frontend experience"]
  node_app["App and routing<br/>[App.tsx]"]
  node_live_ui["Live monitor UI<br/>[LiveMonitor.tsx]"]
  node_history_ui["History UI<br/>[History.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_backend["API and domain"]
  node_sessions_api["Session endpoints<br/>[sessions.py]"]
  node_schemas["API schemas<br/>[sessions.py]"]
  node_session_service["Session lifecycle<br/>[sessions.py]"]
  node_server_verdict["Verdict re-check<br/>[verdict.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_backend_app["API application<br/>[main.py]"]
end

subgraph group_storage["Persistence"]
  node_db_models["Session and samples<br/>[models.py]"]
  node_db_session["Database session<br/>[session.py]"]
  node_postgres[("Postgres")]
end

node_person(("User"))
node_camera(("Webcam"))

node_person -->|"uses"| node_app
node_camera -->|"provides video"| node_camera_access
node_camera_access -->|"supplies frames"| node_frame_loop
node_frame_loop -->|"analyzes frames"| node_frame_analysis
node_frame_loop -->|"detects faces"| node_face_detector
node_frame_analysis -->|"uses"| node_frame_metrics
node_face_detector -->|"filters candidates"| node_face_filter
node_face_detector -->|"measures framing"| node_insights
node_monitor -->|"opens camera"| node_camera_access
node_monitor -->|"runs capture"| node_frame_loop
node_monitor -->|"uses"| node_frame_analysis
node_monitor -->|"uses"| node_face_detector
node_monitor -->|"judges samples"| node_verdict
node_sample_aggregator -->|"aggregates"| node_frame_metrics
node_sample_aggregator -->|"assigns verdict"| node_verdict
node_insight_aggregator -->|"aggregates"| node_frame_metrics
node_insight_aggregator -->|"computes insights"| node_insights
node_monitor -->|"collects samples"| node_sample_aggregator
node_monitor -->|"collects insights"| node_insight_aggregator
node_monitor -->|"queues samples"| node_outbox
node_app -->|"routes to"| node_live_ui
node_app -->|"routes to"| node_history_ui
node_app -->|"shows status"| node_health
node_live_ui -.->|"displays monitoring"| node_monitor
node_outbox -->|"sends batches"| node_api_client
node_api_client -->|"calls session API"| node_sessions_api
node_history_ui -.->|"loads sessions"| node_api_client
node_backend_app -->|"registers routes"| node_sessions_api
node_backend_app -->|"registers routes"| node_health
node_sessions_api -->|"validates payloads"| node_schemas
node_sessions_api -->|"delegates lifecycle"| node_session_service
node_session_service -->|"re-checks verdict"| node_server_verdict
node_session_service -->|"reads and writes"| node_db_models
node_session_service -->|"uses data models"| node_schemas
node_backend_app -->|"creates database session"| node_db_session
node_health -->|"checks database"| node_db_session
node_db_session -->|"connects"| node_postgres

click node_camera_access "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/camera.ts"
click node_frame_loop "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/frameLoop.ts"
click node_face_detector "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/faceDetector.ts"
click node_frame_analysis "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/frameAnalyzer.ts"
click node_frame_metrics "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/frame.ts"
click node_face_filter "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/faceFilter.ts"
click node_verdict "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/verdict.ts"
click node_insights "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/insights.ts"
click node_sample_aggregator "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/aggregator.ts"
click node_insight_aggregator "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/insightAggregator.ts"
click node_monitor "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/monitor.ts"
click node_outbox "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/outbox.ts"
click node_app "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/App.tsx"
click node_live_ui "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/LiveMonitor.tsx"
click node_history_ui "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/History.tsx"
click node_api_client "https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/api/client.ts"
click node_sessions_api "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/api/sessions.py"
click node_schemas "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/schemas/sessions.py"
click node_session_service "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/services/sessions.py"
click node_server_verdict "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/services/verdict.py"
click node_db_models "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/db/models.py"
click node_db_session "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/db/session.py"
click node_health "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/api/health.py"
click node_backend_app "https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/main.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_camera_access,node_frame_loop,node_face_detector,node_frame_analysis,node_person toneBlue
class node_frame_metrics,node_face_filter,node_verdict,node_insights,node_sample_aggregator,node_insight_aggregator,node_monitor,node_outbox toneAmber
class node_app,node_live_ui,node_history_ui,node_api_client toneMint
class node_sessions_api,node_schemas,node_session_service,node_server_verdict,node_health,node_backend_app toneRose
class node_db_models,node_db_session,node_postgres,node_camera toneIndigo
```

## Components

### Browser capture

- [Camera access](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/camera.ts): `frontend/src/capture/camera.ts`
- [Frame loop](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/frameLoop.ts): `frontend/src/capture/frameLoop.ts`
- [Face detection](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/faceDetector.ts): `frontend/src/capture/faceDetector.ts`
- [Frame analysis](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/capture/frameAnalyzer.ts): `frontend/src/capture/frameAnalyzer.ts`

### Metrics and session

- [Frame metrics](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/frame.ts): `frontend/src/metrics/frame.ts`
- [Face filter](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/faceFilter.ts): `frontend/src/metrics/faceFilter.ts`
- [Quality verdict](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/verdict.ts): `frontend/src/metrics/verdict.ts`
- [Extra insights](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/metrics/insights.ts): `frontend/src/metrics/insights.ts`
- [Sample aggregation](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/aggregator.ts): `frontend/src/session/aggregator.ts`
- [Insight aggregation](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/insightAggregator.ts): `frontend/src/session/insightAggregator.ts`
- [Session monitor](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/monitor.ts): `frontend/src/session/monitor.ts`
- [Sample outbox](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/session/outbox.ts): `frontend/src/session/outbox.ts`

### Frontend experience

- [App and routing](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/App.tsx): `frontend/src/ui/App.tsx`
- [Live monitor UI](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/LiveMonitor.tsx): `frontend/src/ui/LiveMonitor.tsx`
- [History UI](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/ui/History.tsx): `frontend/src/ui/History.tsx`
- [API client](https://github.com/eyalshub/live-video-quality-monitor/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and domain

- [Session endpoints](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/api/sessions.py): `backend/app/api/sessions.py`
- [API schemas](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/schemas/sessions.py): `backend/app/schemas/sessions.py`
- [Session lifecycle](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/services/sessions.py): `backend/app/services/sessions.py`
- [Verdict re-check](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/services/verdict.py): `backend/app/services/verdict.py`
- [Health endpoint](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/api/health.py): `backend/app/api/health.py`
- [API application](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/main.py): `backend/app/main.py`

### Persistence

- [Session and samples](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Database session](https://github.com/eyalshub/live-video-quality-monitor/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- **Postgres**

### Other components

- **User**
- **Webcam**

## Connections

- User → App and routing: uses (evidence: `frontend/src/ui/App.tsx`)
- Webcam → Camera access: provides video (evidence: `README.md`)
- Camera access → Frame loop: supplies frames (evidence: `README.md`)
- Frame loop → Frame analysis: analyzes frames (evidence: `README.md`)
- Frame loop → Face detection: detects faces (evidence: `frontend/src/session/monitor.ts`)
- Frame analysis → Frame metrics: uses (evidence: `frontend/src/capture/frameAnalyzer.ts`)
- Face detection → Face filter: filters candidates (evidence: `frontend/src/capture/faceDetector.ts`)
- Face detection → Extra insights: measures framing (evidence: `frontend/src/capture/faceDetector.ts`)
- Session monitor → Camera access: opens camera (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Frame loop: runs capture (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Frame analysis: uses (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Face detection: uses (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Quality verdict: judges samples (evidence: `frontend/src/session/monitor.ts`)
- Sample aggregation → Frame metrics: aggregates (evidence: `frontend/src/session/aggregator.ts`)
- Sample aggregation → Quality verdict: assigns verdict (evidence: `frontend/src/session/aggregator.ts`)
- Insight aggregation → Frame metrics: aggregates (evidence: `frontend/src/session/insightAggregator.ts`)
- Insight aggregation → Extra insights: computes insights (evidence: `frontend/src/session/insightAggregator.ts`)
- Session monitor → Sample aggregation: collects samples (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Insight aggregation: collects insights (evidence: `frontend/src/session/monitor.ts`)
- Session monitor → Sample outbox: queues samples (evidence: `frontend/src/session/monitor.ts`)
- App and routing → Live monitor UI: routes to (evidence: `frontend/src/ui/App.tsx`)
- App and routing → History UI: routes to (evidence: `frontend/src/ui/App.tsx`)
- App and routing → Health endpoint: shows status (evidence: `frontend/src/ui/App.tsx`)
- Live monitor UI → Session monitor: displays monitoring
- Sample outbox → API client: sends batches (evidence: `frontend/src/session/monitor.ts`)
- API client → Session endpoints: calls session API (evidence: `README.md`)
- History UI → API client: loads sessions
- API application → Session endpoints: registers routes (evidence: `backend/app/main.py`)
- API application → Health endpoint: registers routes (evidence: `backend/app/main.py`)
- Session endpoints → API schemas: validates payloads (evidence: `backend/app/api/sessions.py`)
- Session endpoints → Session lifecycle: delegates lifecycle (evidence: `backend/app/api/sessions.py`)
- Session lifecycle → Verdict re-check: re-checks verdict (evidence: `backend/app/services/sessions.py`)
- Session lifecycle → Session and samples: reads and writes (evidence: `backend/app/services/sessions.py`)
- Session lifecycle → API schemas: uses data models (evidence: `backend/app/services/sessions.py`)
- API application → Database session: creates database session (evidence: `backend/app/main.py`)
- Health endpoint → Database session: checks database (evidence: `backend/app/api/health.py`)
- Database session → Postgres: connects (evidence: `README.md`)
