# karinzaa/junctionkanshi architecture

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

- Interactive diagram: https://gitdiagram.com/karinzaa/junctionkanshi
- Repository: https://github.com/karinzaa/junctionkanshi

## Overview

##### Project type and purpose
- This is an IoT-enabled full-stack traffic monitoring and control system.
- Purpose: collect real-time vehicle counts from edge devices, analyze congestion, notify stakeholders (police, tech providers, public), and present data in a web dashboard.

##### File structure
- Top-level modules:
- Traffic-Monitoring (backend Python service)
- Traffic-Notif (edge device firmware in C++/PlatformIO)
- JunctionKanshi-web (static web frontend)
- Traffic-Monitoring contains
- comm_task/mqtt_client.py – subscribes to device data via MQTT
- analysis.py – runs AI/vehicle-detection logic (uses vech.xml)
- main.py – orchestrates data ingestion, analysis, and output
- traffic_data/traffic_data.json – stores or exports processed counts
- static/ – possibly holds assets for dashboard or API
- Traffic-Notif contains firmware for microcontrollers to read sensors and publish MQTT messages.
- JunctionKanshi-web is a PWA-style static site (HTML, CSS, JS, service worker) that fetches traffic_data.json and renders live/offline views.

##### Extract insights from the README
- Stakeholders: traffic controller, tech providers, general public
- User stories require real-time monitoring, device status map, push notifications on congestion

##### Components
a. Devices layer (edge)
- Traffic-Notif microcontrollers (sensor + firmware)
- Communication via MQTT protocol to an MQTT broker
b. Backend services
- MQTT broker (e.g., Mosquitto)
- Python ingestion service (mqtt_client)
- Analysis engine (analysis.py using vech.xml for vehicle detection)
- Data store (traffic_data.json or a database)
- Notification module (triggers alerts when thresholds met)
c. Frontend layer
- Static web application (JunctionKanshi-web) served from web server or CDN
- Service worker for offline support (sw.js)
- Web push or SMS/email gateway for notifications to users
d. External/third-party services
- Mapping API for device location map
- Push notification service (Firebase, Web Push)

##### Relationships and data flows
- Edge device → (MQTT publish) → MQTT broker
- MQTT broker → (MQTT subscribe) → Python ingestion (comm_task)
- Ingestion → (inter-process call) → Analysis engine
- Analysis → (write) → Data store
- Analysis → (trigger) → Notification module → (push) → Stakeholders
- Frontend → (HTTP GET) → Data store or backend API → Renders dashboards
- Frontend → (Web Push registration) → Notification service

##### Architectural patterns and design principles
- Layered architecture: edge, middleware (messaging), backend, frontend
- Event-driven (MQTT topics for data ingestion and notifications)
- Microservices style separation between ingestion, analysis, notifications
- Static-site PWA for scalability and offline support

##### Technologies and frameworks to call out
- MQTT (broker and mqtt_client.py)
- Python 3 for server logic (main.py, analysis.py)
- OpenCV or similar (implied by vech.xml cascade file)
- PlatformIO/C++ for firmware on microcontrollers
- Plain HTML/CSS/JavaScript PWA for frontend
- JSON for data interchange

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Edge Layer
    subgraph "Edge Layer"
        direction TB
        Firmware["Traffic-Notif Firmware"]:::edge
        Config["PlatformIO Config"]:::edge
    end

    %% Middleware Broker
    MQTTBroker("MQTT Broker"):::external

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        MQTTClient["MQTT Ingestion Client"]:::backend
        Orchestrator["Orchestrator Service"]:::backend
        AnalysisEngine["Analysis Engine"]:::backend
        VehicleModel["Vehicle Detection Model"]:::backend
        NotificationModule["Notification Module"]:::backend
        BackendStatic["Backend Static Assets"]:::backend
    end

    %% Data Store
    DataStore["Processed Data Store (JSON)"]:::data

    %% Frontend Layer
    subgraph "Frontend (PWA)" 
        direction TB
        FrontendIndex["index.html"]:::frontend
        FrontendLive["live.html"]:::frontend
        FrontendOffline["offline.html"]:::frontend
        ServiceWorker["sw.js"]:::frontend
        FrontendCSS["mobile.css"]:::frontend
        JSApp["app.js"]:::frontend
        JSLoader["loader.js"]:::frontend
        JSMobile["mobileScript.js"]:::frontend
        JSNum["num.js"]:::frontend
        Manifest["manifest.json"]:::frontend
        CommonMobile["common/mobile/*.html"]:::frontend
    end

    %% External Services
    MappingAPI("Mapping API"):::external
    PushService("Push Notification Service"):::external

    %% Connections
    Firmware -->|"MQTT Publish"| MQTTBroker
    Config --> Firmware
    MQTTBroker -->|"MQTT Subscribe"| MQTTClient
    MQTTClient -->|"forwards data"| Orchestrator
    Orchestrator -->|"runs detection"| AnalysisEngine
    VehicleModel --> AnalysisEngine
    AnalysisEngine -->|"write counts"| DataStore
    AnalysisEngine -->|"trigger alerts"| NotificationModule
    NotificationModule -->|"push alerts"| PushService
    FrontendIndex -->|"HTTP GET data"| DataStore
    FrontendLive --> DataStore
    FrontendOffline --> ServiceWorker
    FrontendIndex -->|"register for push"| PushService
    FrontendIndex -->|"load map"| MappingAPI
    BackendStatic --> FrontendIndex

    %% Click Events
    click Firmware "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Notif/src/main.cpp"
    click Config "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Notif/platformio.ini"
    click MQTTClient "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Monitoring/comm_task/mqtt_client.py"
    click AnalysisEngine "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Monitoring/analysis.py"
    click VehicleModel "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Monitoring/CasCade/vech.xml"
    click Orchestrator "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Monitoring/main.py"
    click DataStore "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-code/Traffic-Monitoring/traffic_data/traffic_data.json"
    click BackendStatic "https://github.com/karinzaa/junctionkanshi/tree/main/JunctionKanshi-code/Traffic-Monitoring/static/"
    click FrontendIndex "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/index.html"
    click FrontendOffline "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/offline.html"
    click FrontendLive "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/live.html"
    click ServiceWorker "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/sw.js"
    click FrontendCSS "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/css/mobile.css"
    click JSApp "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/js/app.js"
    click JSLoader "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/js/loader.js"
    click JSMobile "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/js/mobileScript.js"
    click JSNum "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/js/num.js"
    click Manifest "https://github.com/karinzaa/junctionkanshi/blob/main/JunctionKanshi-web/common/manifest.json"
    click CommonMobile "https://github.com/karinzaa/junctionkanshi/tree/main/JunctionKanshi-web/common/mobile/"

    %% Styles
    classDef edge fill:#c2f0c2,stroke:#2d7b2d,color:#004400;
    classDef backend fill:#c2d9f0,stroke:#1f4e79,color:#001f3f;
    classDef data fill:#f0d9c2,stroke:#79441f,color:#402100;
    classDef frontend fill:#e8c2f0,stroke:#7b2d79,color:#400040;
    classDef external fill:#dddddd,stroke:#888888,color:#333333;
```
