imamh0ssain/traffic-management-system-bangladesh

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.