# imamh0ssain/traffic-management-system-bangladesh architecture

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

- Interactive diagram: https://gitdiagram.com/imamh0ssain/traffic-management-system-bangladesh
- Repository: https://github.com/imamh0ssain/traffic-management-system-bangladesh

## Overview

1. **Repository purpose**
   This is a video analytics application for traffic monitoring. Its core function is to read prerecorded video, detect 11 vehicle classes with a custom YOLOv8 model, track objects across frames with ByteTrack, and produce both a live UI view and an annotated output video.

2. **Top-level execution boundary**
   `run.py` is the main entry point. It branches into two operating modes:
   - **GUI mode** for interactive monitoring
   - **CLI mode** for running inference on a video file without the interface  
   This is the main runtime boundary separating user interaction from the processing pipeline.

3. **Processing pipeline**
   The central runtime flow lives in `src/pipeline.py`. It coordinates the end-to-end video stream processing and is described as multi-threaded, with separate stages for:
   - frame capture
   - detection
   - tracking / post-processing  
   This indicates the system is designed around streaming throughput rather than batch processing.

4. **Detection subsystem**
   `src/detector.py` encapsulates YOLOv8 inference using an exported **ONNX** model. The repository includes both:
   - `models/yolov8n.onnx`
   - `models/yolov8n.engine`  
   The ONNX path is the primary architecture shown in the README, while the TensorRT engine suggests optional accelerated deployment on supported hardware.

5. **Tracking subsystem**
   `src/tracker.py` implements ByteTrack, with Kalman filter smoothing called out in the README. Its role is to assign persistent IDs to detected vehicles across frames, turning per-frame detections into tracked object trajectories and counts.

6. **User interface subsystem**
   `src/gui.py` contains the PyQt5 interface. It presents the live video stream, metrics, and class counts while the pipeline runs. The GUI is not the processing core; it is a consumer of pipeline outputs and status updates.

7. **Metrics and reporting**
   `src/metrics.py` is a separate subsystem for aggregating runtime statistics such as counts and performance-related values. In the architecture diagram, this sits beside tracking rather than inside detection, because its job is to summarize pipeline state for display and reporting.

8. **Configuration boundary**
   `src/config.py` centralizes tunable runtime parameters such as confidence threshold, IoU threshold, and track retention settings like `max_age`. This makes model/pipeline behavior configurable without changing the core modules.

9. **Data flow through the system**
   Input video comes from `data/` or an arbitrary file path in CLI mode. Frames enter the pipeline, are passed to the detector, then to the tracker, then to metrics/UI rendering, and finally to the output writer. The annotated result is saved under `outputs/`.

10. **Model and asset layout**
    The `models/` directory is the inference asset boundary and contains the trained model artifacts. The `data/` directory is input-only sample media, while `outputs/` is the sink for generated annotated videos. These directories are important in a diagram as source, model, and sink zones.

11. **Technology stack that materially affects architecture**
    The system is Python-based, uses **PyQt5** for the interface, **ONNX Runtime** for inference, and optionally **TensorRT/CUDA** for acceleration. That combination explains why the architecture is split between UI, threaded pipeline, and inference/tracking components.

12. **Operational shape**
    The application is oriented toward near-real-time monitoring, not training. The repository contains no training pipeline, database, or network service layer. The architectural focus is therefore a local, video-in/video-out processing engine with an interactive presentation layer.

Main entry points: [`src/pipeline.py`](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py) (Pipeline), [`src/detector.py`](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/detector.py) (Detector), [`src/gui.py`](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/gui.py) (PyQt UI), [`src/main.py`](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/main.py) (Launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_run_py["run.py<br/>entrypoint<br/>[run.py]"]
  node_app_bootstrap["Launcher<br/>bootstrap<br/>[main.py]"]
  node_gui_mode["GUI mode<br/>interactive mode<br/>[gui.py]"]
  node_cli_mode["CLI mode<br/>batch mode<br/>[main.py]"]
end

subgraph group_processing["Processing"]
  node_pipeline{{"Pipeline<br/>streaming core<br/>[pipeline.py]"}}
  node_frame_capture["Capture<br/>ingest stage<br/>[pipeline.py]"]
  node_detector["Detector<br/>YOLOv8 inference<br/>[detector.py]"]
  node_tracker["Tracker<br/>ByteTrack<br/>[tracker.py]"]
  node_metrics["Metrics<br/>aggregation<br/>[metrics.py]"]
  node_postprocess["Post-process<br/>render stage<br/>[pipeline.py]"]
  node_config["Config<br/>runtime settings<br/>[config.py]"]
end

subgraph group_ui["Presentation"]
  node_gui["PyQt UI<br/>presentation<br/>[gui.py]"]
end

subgraph group_assets["Assets"]
  node_input_data["Input videos<br/>video source"]
  node_onnx_model[("YOLOv8 ONNX<br/>model artifact<br/>[yolov8n.onnx]")]
  node_trt_engine[("TensorRT engine<br/>accelerated model<br/>[yolov8n.engine]")]
  node_output_videos["Outputs<br/>render sink"]
end

node_run_py -->|"starts"| node_app_bootstrap
node_app_bootstrap -->|"interactive"| node_gui_mode
node_app_bootstrap -->|"batch"| node_cli_mode
node_gui_mode -->|"uses"| node_gui
node_cli_mode -->|"runs"| node_pipeline
node_gui -->|"consumes"| node_pipeline
node_pipeline -->|"reads"| node_config
node_pipeline -->|"captures"| node_frame_capture
node_frame_capture -->|"loads"| node_input_data
node_frame_capture -->|"feeds"| node_detector
node_detector -->|"inference"| node_onnx_model
node_detector -.->|"optional accel"| node_trt_engine
node_detector -->|"detections"| node_tracker
node_tracker -->|"updates"| node_metrics
node_tracker -->|"tracks"| node_postprocess
node_metrics -->|"displays"| node_gui
node_postprocess -->|"writes"| node_output_videos
node_postprocess -->|"renders"| node_gui
node_pipeline -->|"saves"| node_output_videos

click node_run_py "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/run.py"
click node_app_bootstrap "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/main.py"
click node_gui_mode "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/gui.py"
click node_cli_mode "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/main.py"
click node_pipeline "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py"
click node_frame_capture "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py"
click node_detector "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/detector.py"
click node_tracker "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/tracker.py"
click node_metrics "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/metrics.py"
click node_postprocess "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py"
click node_config "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/config.py"
click node_gui "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/gui.py"
click node_input_data "https://github.com/imamh0ssain/traffic-management-system-bangladesh/tree/main/data"
click node_onnx_model "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/models/yolov8n.onnx"
click node_trt_engine "https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/models/yolov8n.engine"
click node_output_videos "https://github.com/imamh0ssain/traffic-management-system-bangladesh/tree/main/outputs"

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_run_py,node_app_bootstrap,node_gui_mode,node_cli_mode toneBlue
class node_pipeline,node_frame_capture,node_detector,node_tracker,node_metrics,node_postprocess,node_config toneAmber
class node_gui toneMint
class node_input_data,node_onnx_model,node_trt_engine,node_output_videos toneRose
```

## Components

### Runtime

Entry points and operating modes

- [run.py](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/run.py): entrypoint · Main application entrypoint that selects how the app runs · `run.py`
- [Launcher](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/main.py): bootstrap · Initializes the application and routes into GUI or CLI execution · `src/main.py`
- [GUI mode](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/gui.py): interactive mode · Interactive monitoring mode with live video and metrics · `src/gui.py`
- [CLI mode](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/main.py): batch mode · Non-interactive video inference mode · `src/main.py`

### Processing

Video analysis pipeline and core subsystems

- [Pipeline](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py): streaming core · Coordinates threaded video processing end to end · `src/pipeline.py`
- [Capture](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py): ingest stage · Reads frames from prerecorded video input · `src/pipeline.py`
- [Detector](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/detector.py): YOLOv8 inference · Runs object detection using the exported model · `src/detector.py`
- [Tracker](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/tracker.py): ByteTrack · Assigns persistent IDs and smooths trajectories across frames · `src/tracker.py`
- [Metrics](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/metrics.py): aggregation · Aggregates counts and runtime statistics for display and reporting · `src/metrics.py`
- [Post-process](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/pipeline.py): render stage · Combines detections, tracks, and overlays into annotated output · `src/pipeline.py`
- [Config](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/config.py): runtime settings · Centralizes confidence, IoU, and tracking parameters · `src/config.py`

### Presentation

Interactive monitoring interface

- [PyQt UI](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/src/gui.py): presentation · Live video view with metrics and class counts · `src/gui.py`

### Assets

Input videos, model artifacts, and generated outputs

- [Input videos](https://github.com/imamh0ssain/traffic-management-system-bangladesh/tree/main/data): video source · Sample or user-provided prerecorded video files · `data`
- [YOLOv8 ONNX](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/models/yolov8n.onnx): model artifact · Primary inference model used by the detector · `models/yolov8n.onnx`
- [TensorRT engine](https://github.com/imamh0ssain/traffic-management-system-bangladesh/blob/main/models/yolov8n.engine): accelerated model · Optional accelerated deployment artifact · `models/yolov8n.engine`
- [Outputs](https://github.com/imamh0ssain/traffic-management-system-bangladesh/tree/main/outputs): render sink · Annotated video files generated by the pipeline · `outputs`

## Connections

- run.py → Launcher: starts · Launches the application bootstrap
- Launcher → GUI mode: interactive · Routes into the GUI workflow
- Launcher → CLI mode: batch · Routes into the command-line workflow
- GUI mode → PyQt UI: uses · GUI mode is implemented by the PyQt interface
- CLI mode → Pipeline: runs · CLI mode executes the video pipeline without the UI
- PyQt UI → Pipeline: consumes · GUI receives frames, metrics, and status from the pipeline
- Pipeline → Config: reads · Pipeline behavior is controlled by runtime configuration
- Pipeline → Capture: captures · Reads frames from input video
- Capture → Input videos: loads · Video frames come from input files or sample media
- Capture → Detector: feeds · Captured frames are sent for inference
- Detector → YOLOv8 ONNX: inference · Uses the ONNX model for detection
- Detector → TensorRT engine: optional accel · May use the TensorRT engine when available
- Detector → Tracker: detections · Detected objects are forwarded to tracking
- Tracker → Metrics: updates · Track state contributes to counts and statistics
- Tracker → Post-process: tracks · Tracked objects are passed to rendering and annotation
- Metrics → PyQt UI: displays · Metrics are shown in the live interface
- Post-process → Outputs: writes · Annotated video is written to the output directory
- Post-process → PyQt UI: renders · Annotated frames are shown in the live UI
- Pipeline → Outputs: saves · Pipeline persists the finished annotated video