# wydoinn/traffic-vision architecture

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

- Interactive diagram: https://gitdiagram.com/wydoinn/traffic-vision
- Repository: https://github.com/wydoinn/traffic-vision

## Overview

##### Project Type and Purpose
- Full-stack AI + IoT system for traffic monitoring and adaptive signal control.
- Combines a desktop GUI (PyQt6), ML inference (YOLOv8), database storage (SQLite), web dashboard (Streamlit), hardware simulation (Arduino), and notification service (Telegram Bot).

##### File Structure
Top-level modules:
– app.py / main.py: Application startup & main UI window
– controller/: Traffic light control logic
– db/: Data collection and SQLite interaction
– hardware_simulation/: Arduino sketches & PCB design
– inference.py: Video processing & ML inference pipeline
– manager.py: Zone management & overall workflow
– models/: Trained YOLOv8 model configs & results
– static/: UI assets & styles
– ui/: PyQt6 UI components (controls, monitoring, settings, traffic light)
– utils/: Constants, error handling, health monitoring, notification
– visualizer.py: Streamlit analytics dashboard
– config_manager.py: Centralized configuration loader
– logger.py: Application logging
– version.py: Version tracking

##### README for Architecture Clues
- Tech stack: YOLOv8m, PyQt6, SQLite, Streamlit, Arduino, Telegram Bot.

##### Main Components
a. Presentation Layer
– PyQt6 GUI (app.py, main.py, ui/)
– Streamlit Dashboard (visualizer.py)
b. Business Logic Layer
– Zone Manager (manager.py)
– Inference Engine (inference.py + models/)
– Traffic Controller (controller/light_controller.py)
– Configuration Manager (config_manager.py)
– Notification Service (utils/notifier.py → Telegram Bot)
– Logging & Error Handler (logger.py, utils/error_handler.py)
c. Data Layer
– SQLite Database (db/database.py, db/data_collector.py → /data/traffic_data.db)
d. Hardware Layer
– Arduino Traffic Light Simulation (hardware_simulation/*.ino)
e. Auxiliary Services
– Health Monitor (utils/health_monitor.py)
– Constants & Utilities (utils/constants.py)

##### Relationships and Data Flows
1. User launches PyQt6 GUI → loads settings via Config Manager.
2. UI actions (start inference, define zones) → Zone Manager.
3. Zone Manager orchestrates:
- Inference Engine reads video frames → performs Object Detection, Tracking, Heatmap Generation using YOLOv8 models.
- Sends detection events to:
– Traffic Controller → computes signal timings → communicates via Serial to Arduino Simulation.
– Data Collector → writes metrics to SQLite.
– Notification Service → sends Telegram alerts for accidents/emergencies.
4. Database is read by Streamlit Dashboard for historical analysis and real-time charts.
5. Logger captures events/errors at each stage; Health Monitor oversees system status.

##### Architectural Patterns and Design Principles
- Layered architecture (Presentation / Logic / Data / Hardware).
- Modular design: each major function (inference, control, storage, UI) in its own module.
- Event-driven notifications and data collection.
- Clear separation of configuration (config_manager) and logging (logger).

[ ] Main components clearly labeled
[ ] Modular containers for subsystems
[ ] External services and hardware interfaces depicted
[ ] ML models and configuration loading highlighted
[ ] Logging and error handling included

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        PyQt_GUI["PyQt6 GUI"]:::frontend
        Streamlit_Dashboard["Streamlit Dashboard"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Zone_Manager["Zone Manager"]:::business
        Config_Manager["Configuration Manager"]:::business
        Notifier["Notification Service"]:::business
        Traffic_Controller["Traffic Controller"]:::business
        Logger["Logger"]:::util
        Error_Handler["Error Handler"]:::util
        Health_Monitor["Health Monitor"]:::util
        Constants["Constants"]:::util

        subgraph "Inference Engine"
            direction TB
            Inference_Core["Inference Engine"]:::business
            Object_Detection["Object Detection"]:::business
            Tracking["Tracking"]:::business
            Heatmap["Heatmap Generation"]:::business
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Data_Collector["Data Collector"]:::data
        SQLite_DB["SQLite Database"]:::data
    end

    %% Hardware Layer
    subgraph "Hardware Simulation"
        direction TB
        Arduino_Simulation["Arduino Traffic Light Simulation"]:::hardware
    end

    %% Flows and Relationships
    PyQt_GUI -->|"start, zones"| Zone_Manager
    PyQt_GUI -->|"load settings"| Config_Manager
    Zone_Manager -->|"frames"| Inference_Core
    Inference_Core -->|"detections"| Object_Detection
    Inference_Core -->|"tracking data"| Tracking
    Inference_Core -->|"heatmap data"| Heatmap
    Object_Detection -->|"events"| Traffic_Controller
    Object_Detection -->|"events"| Data_Collector
    Object_Detection -->|"alerts"| Notifier
    Traffic_Controller -->|"signal commands"| Arduino_Simulation
    Data_Collector -->|"DB writes"| SQLite_DB
    Streamlit_Dashboard -->|"DB reads"| SQLite_DB
    Logger -->|"logs events/errors"| Zone_Manager
    Logger -->|"logs events/errors"| Inference_Core
    Logger -->|"logs events/errors"| Traffic_Controller
    Health_Monitor -->|"system status"| Zone_Manager

    %% Click Events
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/app.py"
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/main.py"
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/ui/controls.py"
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/ui/monitoring.py"
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/ui/settings.py"
    click PyQt_GUI "https://github.com/wydoinn/traffic-vision/blob/main/ui/traffic_light.py"
    click Streamlit_Dashboard "https://github.com/wydoinn/traffic-vision/blob/main/visualizer.py"
    click Streamlit_Dashboard "https://github.com/wydoinn/traffic-vision/blob/main/visualization/accident.ipynb"
    click Streamlit_Dashboard "https://github.com/wydoinn/traffic-vision/blob/main/visualization/emergency_vehicle.ipynb"
    click Zone_Manager "https://github.com/wydoinn/traffic-vision/blob/main/manager.py"
    click Inference_Core "https://github.com/wydoinn/traffic-vision/blob/main/inference.py"
    click Object_Detection "https://github.com/wydoinn/traffic-vision/tree/main/models/accident-detection/"
    click Object_Detection "https://github.com/wydoinn/traffic-vision/tree/main/models/emergency-vehicle-detection/"
    click Traffic_Controller "https://github.com/wydoinn/traffic-vision/blob/main/controller/light_controller.py"
    click Config_Manager "https://github.com/wydoinn/traffic-vision/blob/main/config_manager.py"
    click Notifier "https://github.com/wydoinn/traffic-vision/blob/main/utils/notifier.py"
    click Logger "https://github.com/wydoinn/traffic-vision/blob/main/logger.py"
    click Error_Handler "https://github.com/wydoinn/traffic-vision/blob/main/utils/error_handler.py"
    click Data_Collector "https://github.com/wydoinn/traffic-vision/blob/main/db/data_collector.py"
    click SQLite_DB "https://github.com/wydoinn/traffic-vision/blob/main/db/database.py"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/sketch1.ino"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/sketch2.ino"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/sketch3.ino"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/Component List.csv"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/Hardware.brd"
    click Arduino_Simulation "https://github.com/wydoinn/traffic-vision/blob/main/hardware_simulation/Schematic View.pdf"
    click Health_Monitor "https://github.com/wydoinn/traffic-vision/blob/main/utils/health_monitor.py"
    click Constants "https://github.com/wydoinn/traffic-vision/blob/main/utils/constants.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef business fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef data fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef hardware fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef util fill:#ECEFF1,stroke:#78909C,color:#263238;
```
