# narusornruengchot/traffic-project architecture

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

- Interactive diagram: https://gitdiagram.com/narusornruengchot/traffic-project
- Repository: https://github.com/narusornruengchot/traffic-project

## Overview

KU SRC is a real-time traffic analytics product: users configure a video or CCTV source and tripwire, start a stream, and receive annotated video, vehicle counts, congestion metrics, and incident alerts; they can also review and export historical reports. The main path runs from the React dashboard through WebSocket commands to a background stream worker and traffic pipeline, with events persisted for reporting. README capabilities also include uploads, model selection, CCTV testing, calibration, and CSV export. Relationships for unsampled modules are included only where the README or SOURCE INDEX supports them.

Main entry points: [`src/core/traffic_pipeline.py`](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/traffic_pipeline.py) (Frame pipeline), [`frontend/src/App.jsx`](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/App.jsx) (Dashboard shell), [`src/api/routers/stream.py`](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/stream.py) (Stream commands), [`src/api/state.py`](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/state.py) (Runtime state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_app["Dashboard shell<br/>[App.jsx]"]
  node_controls["Stream controls<br/>[ControlPanel.jsx]"]
  node_liveview["Live telemetry<br/>[VideoPlayer.jsx]"]
  node_metrics["Metrics and charts"]
  node_events["Event log<br/>[EventLogTable.jsx]"]
  node_historyui["History reports<br/>[HistoryReport.jsx]"]
  node_alerts["Incident alerts<br/>[IncidentAlerts.jsx]"]
  node_wsclient["WebSocket client"]
  node_restclient["REST client<br/>[api.js]"]
end

subgraph group_api["API and control"]
  node_server["FastAPI server<br/>[server.py]"]
  node_streamapi["Stream commands<br/>[stream.py]"]
  node_mediaapi["Media endpoints<br/>[media.py]"]
  node_cctvapi["CCTV testing<br/>[cctv.py]"]
  node_reportsapi["Report endpoints<br/>[reports.py]"]
  node_state["Runtime state<br/>[state.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_engine["Traffic processing"]
  node_worker["Stream worker<br/>[stream_worker.py]"]
  node_pipeline["Frame pipeline"]
  node_detector["Vehicle detection"]
  node_tracker["Vehicle tracking<br/>[vehicle_tracker.py]"]
  node_counter["Tripwire counting<br/>[lane_counter.py]"]
  node_speed["Speed estimation<br/>[speed_estimator.py]"]
  node_analytics["Congestion analytics<br/>[analytics.py]"]
  node_incidents["Incident detection"]
  node_annotator["Frame annotation<br/>[annotator.py]"]
  node_filehelper["Source discovery<br/>[file_helper.py]"]
  node_telemetry["Telemetry schema<br/>[telemetry.py]"]
end

subgraph group_storage["History and reporting"]
  node_database[("SQLite analytics<br/>[db_manager.py]")]
end

node_operator(("Traffic operator"))

node_operator -->|"uses"| node_app
node_app -->|"renders"| node_controls
node_app -->|"renders"| node_liveview
node_app -->|"renders"| node_metrics
node_app -->|"renders"| node_events
node_app -->|"renders"| node_historyui
node_app -->|"renders"| node_alerts
node_app -->|"uses"| node_wsclient
node_controls -->|"requests"| node_restclient
node_historyui -->|"requests"| node_restclient
node_events -->|"requests"| node_restclient
node_wsclient -->|"sends commands"| node_streamapi
node_restclient -->|"calls media routes"| node_mediaapi
node_restclient -->|"calls report routes"| node_reportsapi
node_server -->|"registers"| node_streamapi
node_server -->|"registers"| node_mediaapi
node_server -->|"registers"| node_reportsapi
node_server -->|"registers"| node_cctvapi
node_streamapi -->|"gets runtime state"| node_state
node_streamapi -->|"dispatches commands"| node_worker
node_state -->|"configures defaults"| node_settings
node_state -->|"creates engine"| node_pipeline
node_state -->|"manages worker"| node_worker
node_streamapi -->|"resolves sources"| node_filehelper
node_mediaapi -->|"discovers media"| node_filehelper
node_mediaapi -->|"requests previews"| node_pipeline
node_cctvapi -->|"uses runtime state"| node_state
node_worker -->|"processes frames"| node_pipeline
node_pipeline -->|"detects vehicles"| node_detector
node_pipeline -->|"tracks detections"| node_tracker
node_pipeline -->|"counts crossings"| node_counter
node_pipeline -->|"estimates speed"| node_speed
node_pipeline -->|"scores traffic"| node_analytics
node_pipeline -->|"detects incidents"| node_incidents
node_pipeline -->|"annotates frames"| node_annotator
node_pipeline -->|"produces telemetry"| node_telemetry
node_analytics -->|"uses schema"| node_telemetry
node_worker -->|"persists events and snapshots"| node_database
node_reportsapi -->|"queries history"| node_database

click node_app "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/App.jsx"
click node_controls "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/ControlPanel.jsx"
click node_liveview "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/VideoPlayer.jsx"
click node_metrics "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/AnalyticsCharts.jsx"
click node_events "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/EventLogTable.jsx"
click node_historyui "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/HistoryReport.jsx"
click node_alerts "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/IncidentAlerts.jsx"
click node_wsclient "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/hooks/useTrafficWebSocket.js"
click node_restclient "https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/narusornruengchot/traffic-project/blob/main/server.py"
click node_streamapi "https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/stream.py"
click node_mediaapi "https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/media.py"
click node_cctvapi "https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/cctv.py"
click node_reportsapi "https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/reports.py"
click node_state "https://github.com/narusornruengchot/traffic-project/blob/main/src/api/state.py"
click node_settings "https://github.com/narusornruengchot/traffic-project/blob/main/src/config/settings.py"
click node_worker "https://github.com/narusornruengchot/traffic-project/blob/main/src/services/stream_worker.py"
click node_pipeline "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/traffic_pipeline.py"
click node_detector "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/vehicle_detector.py"
click node_tracker "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/vehicle_tracker.py"
click node_counter "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/lane_counter.py"
click node_speed "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/speed_estimator.py"
click node_analytics "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/analytics.py"
click node_incidents "https://github.com/narusornruengchot/traffic-project/blob/main/src/core/incident_detector.py"
click node_annotator "https://github.com/narusornruengchot/traffic-project/blob/main/src/visualizer/annotator.py"
click node_filehelper "https://github.com/narusornruengchot/traffic-project/blob/main/src/utils/file_helper.py"
click node_telemetry "https://github.com/narusornruengchot/traffic-project/blob/main/src/schema/telemetry.py"
click node_database "https://github.com/narusornruengchot/traffic-project/blob/main/src/database/db_manager.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_app,node_controls,node_liveview,node_metrics,node_events,node_historyui,node_alerts,node_wsclient,node_restclient toneBlue
class node_server,node_streamapi,node_mediaapi,node_cctvapi,node_reportsapi,node_state,node_settings toneAmber
class node_worker,node_pipeline,node_detector,node_tracker,node_counter,node_speed,node_analytics,node_incidents,node_annotator,node_filehelper,node_telemetry toneMint
class node_database toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [Dashboard shell](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Stream controls](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/ControlPanel.jsx): `frontend/src/components/ControlPanel.jsx`
- [Live telemetry](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/VideoPlayer.jsx): `frontend/src/components/VideoPlayer.jsx`
- [Metrics and charts](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/AnalyticsCharts.jsx): `frontend/src/components/AnalyticsCharts.jsx`
- [Event log](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/EventLogTable.jsx): `frontend/src/components/EventLogTable.jsx`
- [History reports](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/HistoryReport.jsx): `frontend/src/components/HistoryReport.jsx`
- [Incident alerts](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/components/IncidentAlerts.jsx): `frontend/src/components/IncidentAlerts.jsx`
- [WebSocket client](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/hooks/useTrafficWebSocket.js): `frontend/src/hooks/useTrafficWebSocket.js`
- [REST client](https://github.com/narusornruengchot/traffic-project/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and control

- [FastAPI server](https://github.com/narusornruengchot/traffic-project/blob/main/server.py): `server.py`
- [Stream commands](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/stream.py): `src/api/routers/stream.py`
- [Media endpoints](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/media.py): `src/api/routers/media.py`
- [CCTV testing](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/cctv.py): `src/api/routers/cctv.py`
- [Report endpoints](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/routers/reports.py): `src/api/routers/reports.py`
- [Runtime state](https://github.com/narusornruengchot/traffic-project/blob/main/src/api/state.py): `src/api/state.py`
- [Runtime settings](https://github.com/narusornruengchot/traffic-project/blob/main/src/config/settings.py): `src/config/settings.py`

### Traffic processing

- [Stream worker](https://github.com/narusornruengchot/traffic-project/blob/main/src/services/stream_worker.py): `src/services/stream_worker.py`
- [Frame pipeline](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/traffic_pipeline.py): `src/core/traffic_pipeline.py`
- [Vehicle detection](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/vehicle_detector.py): `src/core/vehicle_detector.py`
- [Vehicle tracking](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/vehicle_tracker.py): `src/core/vehicle_tracker.py`
- [Tripwire counting](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/lane_counter.py): `src/core/lane_counter.py`
- [Speed estimation](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/speed_estimator.py): `src/core/speed_estimator.py`
- [Congestion analytics](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/analytics.py): `src/core/analytics.py`
- [Incident detection](https://github.com/narusornruengchot/traffic-project/blob/main/src/core/incident_detector.py): `src/core/incident_detector.py`
- [Frame annotation](https://github.com/narusornruengchot/traffic-project/blob/main/src/visualizer/annotator.py): `src/visualizer/annotator.py`
- [Source discovery](https://github.com/narusornruengchot/traffic-project/blob/main/src/utils/file_helper.py): `src/utils/file_helper.py`
- [Telemetry schema](https://github.com/narusornruengchot/traffic-project/blob/main/src/schema/telemetry.py): `src/schema/telemetry.py`

### History and reporting

- [SQLite analytics](https://github.com/narusornruengchot/traffic-project/blob/main/src/database/db_manager.py): `src/database/db_manager.py`

### Other components

- **Traffic operator**

## Connections

- Traffic operator → Dashboard shell: uses (evidence: `README.md`)
- Dashboard shell → Stream controls: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → Live telemetry: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → Metrics and charts: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → Event log: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → History reports: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → Incident alerts: renders (evidence: `frontend/src/App.jsx`)
- Dashboard shell → WebSocket client: uses (evidence: `frontend/src/App.jsx`)
- Stream controls → REST client: requests (evidence: `frontend/src/components/ControlPanel.jsx`)
- History reports → REST client: requests (evidence: `frontend/src/components/HistoryReport.jsx`)
- Event log → REST client: requests (evidence: `frontend/src/components/EventLogTable.jsx`)
- WebSocket client → Stream commands: sends commands (evidence: `README.md`)
- REST client → Media endpoints: calls media routes (evidence: `frontend/src/services/api.js`)
- REST client → Report endpoints: calls report routes (evidence: `frontend/src/services/api.js`)
- FastAPI server → Stream commands: registers (evidence: `server.py`)
- FastAPI server → Media endpoints: registers (evidence: `server.py`)
- FastAPI server → Report endpoints: registers (evidence: `server.py`)
- FastAPI server → CCTV testing: registers (evidence: `server.py`)
- Stream commands → Runtime state: gets runtime state (evidence: `src/api/routers/stream.py`)
- Stream commands → Stream worker: dispatches commands (evidence: `src/api/routers/stream.py`)
- Runtime state → Runtime settings: configures defaults (evidence: `src/api/state.py`)
- Runtime state → Frame pipeline: creates engine (evidence: `src/api/state.py`)
- Runtime state → Stream worker: manages worker (evidence: `src/api/state.py`)
- Stream commands → Source discovery: resolves sources (evidence: `src/api/routers/stream.py`)
- Media endpoints → Source discovery: discovers media (evidence: `src/api/routers/media.py`)
- Media endpoints → Frame pipeline: requests previews (evidence: `src/api/routers/media.py`)
- CCTV testing → Runtime state: uses runtime state (evidence: `src/api/routers/cctv.py`)
- Stream worker → Frame pipeline: processes frames (evidence: `src/services/stream_worker.py`)
- Frame pipeline → Vehicle detection: detects vehicles (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Vehicle tracking: tracks detections (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Tripwire counting: counts crossings (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Speed estimation: estimates speed (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Congestion analytics: scores traffic (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Incident detection: detects incidents (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Frame annotation: annotates frames (evidence: `src/core/traffic_pipeline.py`)
- Frame pipeline → Telemetry schema: produces telemetry (evidence: `src/core/traffic_pipeline.py`)
- Congestion analytics → Telemetry schema: uses schema (evidence: `src/core/analytics.py`)
- Stream worker → SQLite analytics: persists events and snapshots (evidence: `src/services/stream_worker.py`)
- Report endpoints → SQLite analytics: queries history (evidence: `src/api/routers/reports.py`)