# karimelbasiouni/traffilytics architecture

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

- Interactive diagram: https://gitdiagram.com/karimelbasiouni/traffilytics
- Repository: https://github.com/karimelbasiouni/traffilytics

## Overview

Traffilytics turns uploaded traffic video into vehicle detections, tracked trajectories, lane/zone assignments, traffic analytics and reports, exposed through an API and interactive dashboard. Its principal runtime path is job-driven: ingest frames and metadata, detect vehicles, track them, analyze trajectories, then persist results. Separate dataset and model-training/evaluation capabilities support the detector. The excerpts and SOURCE INDEX establish the main orchestration and module relationships; some route and dashboard details are unsampled, so those links are shown only where documented or indexed.

Main entry points: [`backend/services/pipeline.py`](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/services/pipeline.py) (Pipeline worker), [`backend/api/app.py`](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/app.py) (HTTP API), [`backend/api/routes/videos.py`](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/videos.py) (Video routes), [`frontend/src/api.ts`](https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_dashboard["Dashboard<br/>[Overview.tsx]"]
  node_jobui["Job monitor<br/>[Jobs.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_backend["API and jobs"]
  node_api["HTTP API<br/>[app.py]"]
  node_video_routes["Video routes<br/>[videos.py]"]
  node_analytics_routes["Analytics routes<br/>[analytics.py]"]
  node_event_routes["Event routes<br/>[events.py]"]
  node_job_service["Job broker<br/>[jobs.py]"]
  node_worker["Pipeline worker<br/>[pipeline.py]"]
end

subgraph group_vision["Video intelligence"]
  node_video_processor["Video ingestion<br/>[video_processor.py]"]
  node_detector["OBB detector<br/>[detector.py]"]
  node_tracker["Vehicle tracker<br/>[tracker.py]"]
  node_lane_assigner["Lane assignment<br/>[lanes.py]"]
  node_trajectory_generator["Trajectory generation<br/>[generator.py]"]
  node_overlay["Tracking overlays<br/>[overlay.py]"]
end

subgraph group_analytics["Traffic analytics"]
  node_analytics_engine["Analytics engine<br/>[engine.py]"]
  node_analytics_methods["Flow, events, insights"]
end

subgraph group_models["Data and model lifecycle"]
  node_database[("SQL database<br/>[session.py]")]
  node_persistence["Result persistence<br/>[persist.py]"]
  node_dataset["UAV-OBB adapter"]
  node_training["OBB training<br/>[trainer.py]"]
  node_evaluation["Detector evaluation<br/>[evaluator.py]"]
end

node_user(("Video analyst"))

node_user -->|"uploads video"| node_dashboard
node_dashboard -->|"requests data"| node_frontend_api
node_jobui -->|"checks jobs"| node_frontend_api
node_frontend_api -.->|"calls HTTP API"| node_api
node_api -->|"registers routes"| node_video_routes
node_api -->|"registers routes"| node_analytics_routes
node_api -->|"registers routes"| node_event_routes
node_video_routes -->|"reads metadata"| node_video_processor
node_video_routes -->|"queues processing"| node_job_service
node_job_service -->|"runs pipeline"| node_worker
node_worker -->|"extracts frames"| node_video_processor
node_worker -->|"detects vehicles"| node_detector
node_worker -->|"tracks detections"| node_tracker
node_worker -->|"generates tracks"| node_trajectory_generator
node_worker -->|"assigns lanes"| node_lane_assigner
node_worker -->|"analyzes trajectories"| node_analytics_engine
node_analytics_engine -->|"computes metrics"| node_analytics_methods
node_worker -->|"persists results"| node_persistence
node_persistence -->|"writes records"| node_database
node_video_routes -->|"reads video records"| node_database
node_worker -->|"renders overlays"| node_overlay
node_dataset -.->|"provides dataset"| node_training
node_training -.->|"produces weights"| node_detector
node_evaluation -->|"evaluates model"| node_detector

click node_dashboard "https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/pages/Overview.tsx"
click node_jobui "https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/pages/Jobs.tsx"
click node_frontend_api "https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/api.ts"
click node_api "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/app.py"
click node_video_routes "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/videos.py"
click node_analytics_routes "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/analytics.py"
click node_event_routes "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/events.py"
click node_job_service "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/services/jobs.py"
click node_worker "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/services/pipeline.py"
click node_video_processor "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/preprocessing/video_processor.py"
click node_detector "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/detector.py"
click node_tracker "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/tracking/tracker.py"
click node_lane_assigner "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/trajectories/lanes.py"
click node_trajectory_generator "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/trajectories/generator.py"
click node_overlay "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/tracking/overlay.py"
click node_analytics_engine "https://github.com/karimelbasiouni/traffilytics/blob/main/analytics/engine.py"
click node_analytics_methods "https://github.com/karimelbasiouni/traffilytics/tree/main/analytics"
click node_database "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/database/session.py"
click node_persistence "https://github.com/karimelbasiouni/traffilytics/blob/main/backend/database/persist.py"
click node_dataset "https://github.com/karimelbasiouni/traffilytics/tree/main/adapters/uav_obb"
click node_training "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/trainer.py"
click node_evaluation "https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/evaluator.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_dashboard,node_jobui,node_frontend_api toneBlue
class node_api,node_video_routes,node_analytics_routes,node_event_routes,node_job_service,node_worker toneAmber
class node_video_processor,node_detector,node_tracker,node_lane_assigner,node_trajectory_generator,node_overlay toneMint
class node_analytics_engine,node_analytics_methods toneRose
class node_database,node_persistence,node_dataset,node_training,node_evaluation,node_user toneIndigo
```

## Components

### User interface

- [Dashboard](https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/pages/Overview.tsx): `frontend/src/pages/Overview.tsx`
- [Job monitor](https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/pages/Jobs.tsx): `frontend/src/pages/Jobs.tsx`
- [API client](https://github.com/karimelbasiouni/traffilytics/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and jobs

- [HTTP API](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/app.py): `backend/api/app.py`
- [Video routes](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/videos.py): `backend/api/routes/videos.py`
- [Analytics routes](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/analytics.py): `backend/api/routes/analytics.py`
- [Event routes](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/api/routes/events.py): `backend/api/routes/events.py`
- [Job broker](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/services/jobs.py): `backend/services/jobs.py`
- [Pipeline worker](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/services/pipeline.py): `backend/services/pipeline.py`

### Video intelligence

- [Video ingestion](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/preprocessing/video_processor.py): `computer_vision/preprocessing/video_processor.py`
- [OBB detector](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/detector.py): `computer_vision/detection/detector.py`
- [Vehicle tracker](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/tracking/tracker.py): `computer_vision/tracking/tracker.py`
- [Lane assignment](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/trajectories/lanes.py): `computer_vision/trajectories/lanes.py`
- [Trajectory generation](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/trajectories/generator.py): `computer_vision/trajectories/generator.py`
- [Tracking overlays](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/tracking/overlay.py): `computer_vision/tracking/overlay.py`

### Traffic analytics

- [Analytics engine](https://github.com/karimelbasiouni/traffilytics/blob/main/analytics/engine.py): `analytics/engine.py`
- [Flow, events, insights](https://github.com/karimelbasiouni/traffilytics/tree/main/analytics): `analytics`

### Data and model lifecycle

- [SQL database](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/database/session.py): `backend/database/session.py`
- [Result persistence](https://github.com/karimelbasiouni/traffilytics/blob/main/backend/database/persist.py): `backend/database/persist.py`
- [UAV-OBB adapter](https://github.com/karimelbasiouni/traffilytics/tree/main/adapters/uav_obb): `adapters/uav_obb`
- [OBB training](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/trainer.py): `computer_vision/detection/trainer.py`
- [Detector evaluation](https://github.com/karimelbasiouni/traffilytics/blob/main/computer_vision/detection/evaluator.py): `computer_vision/detection/evaluator.py`

### Other components

- **Video analyst**

## Connections

- Video analyst → Dashboard: uploads video (evidence: `README.md`)
- Dashboard → API client: requests data (evidence: `frontend/src/pages/Overview.tsx`)
- Job monitor → API client: checks jobs (evidence: `frontend/src/pages/Jobs.tsx`)
- API client → HTTP API: calls HTTP API
- HTTP API → Video routes: registers routes (evidence: `backend/api/app.py`)
- HTTP API → Analytics routes: registers routes (evidence: `backend/api/app.py`)
- HTTP API → Event routes: registers routes (evidence: `backend/api/app.py`)
- Video routes → Video ingestion: reads metadata (evidence: `backend/api/routes/videos.py`)
- Video routes → Job broker: queues processing (evidence: `backend/api/routes/videos.py`)
- Job broker → Pipeline worker: runs pipeline (evidence: `backend/api/app.py`)
- Pipeline worker → Video ingestion: extracts frames (evidence: `backend/services/pipeline.py`)
- Pipeline worker → OBB detector: detects vehicles (evidence: `backend/services/pipeline.py`)
- Pipeline worker → Vehicle tracker: tracks detections (evidence: `backend/services/pipeline.py`)
- Pipeline worker → Trajectory generation: generates tracks (evidence: `backend/services/pipeline.py`)
- Pipeline worker → Lane assignment: assigns lanes (evidence: `backend/services/pipeline.py`)
- Pipeline worker → Analytics engine: analyzes trajectories (evidence: `backend/services/pipeline.py`)
- Analytics engine → Flow, events, insights: computes metrics (evidence: `analytics/engine.py`)
- Pipeline worker → Result persistence: persists results (evidence: `backend/services/pipeline.py`)
- Result persistence → SQL database: writes records (evidence: `backend/database/persist.py`)
- Video routes → SQL database: reads video records (evidence: `backend/api/routes/videos.py`)
- Pipeline worker → Tracking overlays: renders overlays (evidence: `backend/services/pipeline.py`)
- UAV-OBB adapter → OBB training: provides dataset
- OBB training → OBB detector: produces weights
- Detector evaluation → OBB detector: evaluates model (evidence: `computer_vision/detection/evaluator.py`)
