# mandar885/traffic_vision architecture

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

- Interactive diagram: https://gitdiagram.com/mandar885/traffic_vision
- Repository: https://github.com/mandar885/traffic_vision

## Overview

TrafficVision accepts a traffic video, creates an asynchronous job, analyzes frames for vehicle detections and tracks, updates job analytics, and serves the annotated video and results to a polling React dashboard. The backend separates job/API handling, video processing, and analytics; the frontend separates upload, job polling, and presentation. The job store is in-memory, while uploaded and generated videos use filesystem storage. Unsampled UI and deployment details are omitted; documented capabilities are retained where their implementation is not shown.

Main entry points: [`backend/app/api/jobs.py`](https://github.com/mandar885/traffic_vision/blob/main/backend/app/api/jobs.py) (Job endpoints), [`backend/app/services/video_processor.py`](https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/video_processor.py) (Video processing), [`backend/app/main.py`](https://github.com/mandar885/traffic_vision/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/pages/Dashboard.tsx`](https://github.com/mandar885/traffic_vision/blob/main/frontend/src/pages/Dashboard.tsx) (Dashboard and results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_dashboard["Dashboard and results<br/>[Dashboard.tsx]"]
  node_upload["Video upload panel<br/>[UploadPanel.tsx]"]
  node_job_hook["Job polling hook<br/>[useJob.ts]"]
end

subgraph group_api["Job API"]
  node_api_main["FastAPI application<br/>[main.py]"]
  node_jobs_api["Job endpoints<br/>[jobs.py]"]
  node_job_schema["Job response schema<br/>[jobs.py]"]
end

subgraph group_analysis["Video analysis"]
  node_video_processor["Video processing<br/>[video_processor.py]"]
  node_vehicle_model["YOLO detection and ByteTrack<br/>[video_processor.py]"]
  node_analytics["Traffic analytics<br/>[analytics.py]"]
end

subgraph group_runtime["Runtime state"]
  node_config["Model and service settings<br/>[config.py]"]
  node_security["Filename safety<br/>[security.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_job_store[("In-memory job store<br/>[job_store.py]")]
  node_video_files[("Uploaded and result videos")]
end

node_user(("Video analyst"))

node_user -->|"selects video"| node_upload
node_app -->|"renders"| node_dashboard
node_dashboard -->|"renders"| node_upload
node_dashboard -->|"uses job state"| node_job_hook
node_dashboard -.->|"requests results"| node_api_main
node_job_hook -->|"calls job endpoints"| node_api_main
node_api_main -->|"routes jobs"| node_jobs_api
node_api_main -->|"loads settings"| node_config
node_api_main -->|"configures logging"| node_logging
node_jobs_api -->|"loads settings"| node_config
node_jobs_api -->|"sanitizes filename"| node_security
node_jobs_api -->|"serializes response"| node_job_schema
node_jobs_api -->|"creates and updates jobs"| node_job_store
node_jobs_api -->|"dispatches processing"| node_video_processor
node_jobs_api -->|"writes and serves videos"| node_video_files
node_video_processor -->|"reads and updates jobs"| node_job_store
node_video_processor -->|"loads analysis settings"| node_config
node_video_processor -->|"runs detection and tracking"| node_vehicle_model
node_video_processor -->|"updates frame analytics"| node_analytics
node_video_processor -->|"reads and writes videos"| node_video_files

click node_app "https://github.com/mandar885/traffic_vision/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/mandar885/traffic_vision/blob/main/frontend/src/pages/Dashboard.tsx"
click node_upload "https://github.com/mandar885/traffic_vision/blob/main/frontend/src/components/UploadPanel.tsx"
click node_job_hook "https://github.com/mandar885/traffic_vision/blob/main/frontend/src/hooks/useJob.ts"
click node_api_main "https://github.com/mandar885/traffic_vision/blob/main/backend/app/main.py"
click node_jobs_api "https://github.com/mandar885/traffic_vision/blob/main/backend/app/api/jobs.py"
click node_job_schema "https://github.com/mandar885/traffic_vision/blob/main/backend/app/schemas/jobs.py"
click node_config "https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/config.py"
click node_security "https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/security.py"
click node_logging "https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/logging.py"
click node_job_store "https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/job_store.py"
click node_video_processor "https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/video_processor.py"
click node_vehicle_model "https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/video_processor.py"
click node_analytics "https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/analytics.py"
click node_video_files "https://github.com/mandar885/traffic_vision/tree/main/backend/storage"

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_dashboard,node_upload,node_job_hook toneBlue
class node_api_main,node_jobs_api,node_job_schema toneAmber
class node_video_processor,node_vehicle_model,node_analytics toneMint
class node_config,node_security,node_logging,node_job_store,node_video_files toneRose
class node_user toneIndigo
```

## Components

### Web interface

- [Application shell](https://github.com/mandar885/traffic_vision/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard and results](https://github.com/mandar885/traffic_vision/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Video upload panel](https://github.com/mandar885/traffic_vision/blob/main/frontend/src/components/UploadPanel.tsx): `frontend/src/components/UploadPanel.tsx`
- [Job polling hook](https://github.com/mandar885/traffic_vision/blob/main/frontend/src/hooks/useJob.ts): `frontend/src/hooks/useJob.ts`

### Job API

- [FastAPI application](https://github.com/mandar885/traffic_vision/blob/main/backend/app/main.py): `backend/app/main.py`
- [Job endpoints](https://github.com/mandar885/traffic_vision/blob/main/backend/app/api/jobs.py): `backend/app/api/jobs.py`
- [Job response schema](https://github.com/mandar885/traffic_vision/blob/main/backend/app/schemas/jobs.py): `backend/app/schemas/jobs.py`

### Video analysis

- [Video processing](https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/video_processor.py): `backend/app/services/video_processor.py`
- [YOLO detection and ByteTrack](https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/video_processor.py): `backend/app/services/video_processor.py`
- [Traffic analytics](https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/analytics.py): `backend/app/services/analytics.py`

### Runtime state

- [Model and service settings](https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Filename safety](https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Structured logging](https://github.com/mandar885/traffic_vision/blob/main/backend/app/core/logging.py): `backend/app/core/logging.py`
- [In-memory job store](https://github.com/mandar885/traffic_vision/blob/main/backend/app/services/job_store.py): `backend/app/services/job_store.py`
- [Uploaded and result videos](https://github.com/mandar885/traffic_vision/tree/main/backend/storage): `backend/storage`

### Other components

- **Video analyst**

## Connections

- Video analyst → Video upload panel: selects video (evidence: `frontend/src/components/UploadPanel.tsx`)
- Application shell → Dashboard and results: renders (evidence: `frontend/src/App.tsx`)
- Dashboard and results → Video upload panel: renders (evidence: `frontend/src/pages/Dashboard.tsx`)
- Dashboard and results → Job polling hook: uses job state (evidence: `frontend/src/pages/Dashboard.tsx`)
- Dashboard and results → FastAPI application: requests results (evidence: `README.md`)
- Job polling hook → FastAPI application: calls job endpoints (evidence: `frontend/src/hooks/useJob.ts`)
- FastAPI application → Job endpoints: routes jobs (evidence: `backend/app/main.py`)
- FastAPI application → Model and service settings: loads settings (evidence: `backend/app/main.py`)
- FastAPI application → Structured logging: configures logging (evidence: `backend/app/main.py`)
- Job endpoints → Model and service settings: loads settings (evidence: `backend/app/api/jobs.py`)
- Job endpoints → Filename safety: sanitizes filename (evidence: `backend/app/api/jobs.py`)
- Job endpoints → Job response schema: serializes response (evidence: `backend/app/api/jobs.py`)
- Job endpoints → In-memory job store: creates and updates jobs (evidence: `backend/app/api/jobs.py`)
- Job endpoints → Video processing: dispatches processing (evidence: `backend/app/api/jobs.py`)
- Job endpoints → Uploaded and result videos: writes and serves videos (evidence: `backend/app/api/jobs.py`)
- Video processing → In-memory job store: reads and updates jobs (evidence: `backend/app/services/video_processor.py`)
- Video processing → Model and service settings: loads analysis settings (evidence: `backend/app/services/video_processor.py`)
- Video processing → YOLO detection and ByteTrack: runs detection and tracking (evidence: `backend/app/services/video_processor.py`)
- Video processing → Traffic analytics: updates frame analytics (evidence: `backend/app/services/video_processor.py`)
- Video processing → Uploaded and result videos: reads and writes videos (evidence: `backend/app/services/video_processor.py`)
