# hploc17/edge-ai architecture

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

- Interactive diagram: https://gitdiagram.com/hploc17/edge-ai
- Repository: https://github.com/hploc17/edge-ai

## Overview

This repository implements an edge-to-operations traffic-monitoring system: Jetson video feeds are analyzed for vehicle counts, calibrated speed, and congestion; telemetry and snapshots are sent to a WebGIS backend, where operators inspect the fleet and issue commands. The graph includes the documented edge analytics stages and the sampled backend/frontend flow. Some edge modules and routers are represented by their exact enclosing paths because their implementations were not sampled; links to those modules are limited to documented or visible orchestration.

Main entry points: [`main.py`](https://github.com/hploc17/edge-ai/blob/main/main.py) (Edge orchestrator), [`webgis/frontend/src/App.tsx`](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/App.tsx) (WebGIS application), [`webgis/backend/services/mqtt_service.py`](https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/mqtt_service.py) (Backend MQTT service), [`communication/mqtt_client.py`](https://github.com/hploc17/edge-ai/blob/main/communication/mqtt_client.py) (Edge MQTT client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge analytics"]
  node_main["Edge orchestrator<br/>[main.py]"]
  node_pipeline["GStreamer pipeline"]
  node_roi["ROI management<br/>[roi_manager.py]"]
  node_geometry["ROI geometry<br/>[geometry_utils.py]"]
  node_presence["Vehicle counts"]
  node_speed["Speed estimates<br/>[speed_estimator.py]"]
  node_classification["Traffic classification"]
end

subgraph group_snapshot["Snapshot delivery"]
  node_snapshot_service["Snapshot service"]
  node_outbox[("Offline outbox<br/>[outbox.py]")]
end

subgraph group_communication["Edge communications"]
  node_mqtt_edge["Edge MQTT client<br/>[mqtt_client.py]"]
  node_command_router["Command router<br/>[command_router.py]"]
  node_metrics["System metrics<br/>[system_metrics.py]"]
end

subgraph group_backend["WebGIS backend"]
  node_backend_main["Backend API<br/>[main.py]"]
  node_routers["API routers"]
  node_mqtt_service["Backend MQTT service<br/>[mqtt_service.py]"]
  node_data_store[("Node data store<br/>[data_store.py]")]
  node_websocket_manager["WebSocket manager"]
end

subgraph group_frontend["WebGIS frontend"]
  node_app["WebGIS application<br/>[App.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
  node_ws_client["Frontend WebSocket<br/>[websocket.ts]"]
  node_map["Traffic map<br/>[WebGISMap.tsx]"]
  node_fleet["Fleet management"]
  node_history["Congestion history"]
end

node_operator(("Operator"))
node_video_source(("Video source"))
node_broker(("MQTT broker"))
node_snapshot_api(("Snapshot API"))

node_video_source -->|"supplies frames"| node_pipeline
node_main -->|"builds pipeline"| node_pipeline
node_main -->|"loads ROI"| node_roi
node_roi -->|"uses geometry"| node_geometry
node_main -->|"computes counts"| node_presence
node_main -->|"estimates speed"| node_speed
node_main -->|"classifies traffic"| node_classification
node_main -->|"starts and updates"| node_snapshot_service
node_main -->|"publishes telemetry"| node_mqtt_edge
node_main -->|"routes commands"| node_command_router
node_main -->|"collects metrics"| node_metrics
node_snapshot_service -->|"stores pending images"| node_outbox
node_snapshot_service -->|"uploads snapshots"| node_snapshot_api
node_mqtt_edge -->|"publishes and subscribes"| node_broker
node_broker -->|"forwards telemetry and commands"| node_mqtt_service
node_mqtt_service -->|"updates node state"| node_data_store
node_mqtt_service -->|"broadcasts updates"| node_websocket_manager
node_mqtt_service -->|"publishes commands"| node_broker
node_mqtt_edge -->|"dispatches commands"| node_command_router
node_command_router -->|"reports command results"| node_mqtt_edge
node_backend_main -->|"starts service"| node_mqtt_service
node_backend_main -->|"serves WebSocket"| node_websocket_manager
node_backend_main -->|"registers routes"| node_routers
node_operator -->|"uses WebGIS"| node_app
node_app -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_routers
node_app -->|"receives live updates"| node_ws_client
node_ws_client -->|"connects and receives"| node_websocket_manager
node_app -->|"renders map"| node_map
node_app -->|"opens fleet tools"| node_fleet
node_app -->|"opens history"| node_history

click node_main "https://github.com/hploc17/edge-ai/blob/main/main.py"
click node_pipeline "https://github.com/hploc17/edge-ai/blob/main/core/gstreamer_builder.py"
click node_roi "https://github.com/hploc17/edge-ai/blob/main/spatial/roi_manager.py"
click node_geometry "https://github.com/hploc17/edge-ai/blob/main/spatial/geometry_utils.py"
click node_presence "https://github.com/hploc17/edge-ai/blob/main/analytics/presence_counter.py"
click node_speed "https://github.com/hploc17/edge-ai/blob/main/analytics/speed_estimator.py"
click node_classification "https://github.com/hploc17/edge-ai/blob/main/analytics/traffic_classifier.py"
click node_snapshot_service "https://github.com/hploc17/edge-ai/blob/main/snap/snapshot_service.py"
click node_outbox "https://github.com/hploc17/edge-ai/blob/main/snap/outbox.py"
click node_mqtt_edge "https://github.com/hploc17/edge-ai/blob/main/communication/mqtt_client.py"
click node_command_router "https://github.com/hploc17/edge-ai/blob/main/communication/command_router.py"
click node_metrics "https://github.com/hploc17/edge-ai/blob/main/communication/system_metrics.py"
click node_backend_main "https://github.com/hploc17/edge-ai/blob/main/webgis/backend/main.py"
click node_routers "https://github.com/hploc17/edge-ai/tree/main/webgis/backend/routers"
click node_mqtt_service "https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/mqtt_service.py"
click node_data_store "https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/data_store.py"
click node_websocket_manager "https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/websocket_manager.py"
click node_app "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/App.tsx"
click node_api_client "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/services/api.ts"
click node_ws_client "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/services/websocket.ts"
click node_map "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/Map/WebGISMap.tsx"
click node_fleet "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/Fleet/NodeManagementPanel.tsx"
click node_history "https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/History/CongestionHistoryModal.tsx"

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_main,node_pipeline,node_roi,node_geometry,node_presence,node_speed,node_classification toneBlue
class node_snapshot_service,node_outbox toneAmber
class node_mqtt_edge,node_command_router,node_metrics,node_snapshot_api toneMint
class node_backend_main,node_routers,node_mqtt_service,node_data_store,node_websocket_manager toneRose
class node_app,node_api_client,node_ws_client,node_map,node_fleet,node_history,node_operator,node_video_source,node_broker toneIndigo
```

## Components

### Edge analytics

- [Edge orchestrator](https://github.com/hploc17/edge-ai/blob/main/main.py): `main.py`
- [GStreamer pipeline](https://github.com/hploc17/edge-ai/blob/main/core/gstreamer_builder.py): `core/gstreamer_builder.py`
- [ROI management](https://github.com/hploc17/edge-ai/blob/main/spatial/roi_manager.py): `spatial/roi_manager.py`
- [ROI geometry](https://github.com/hploc17/edge-ai/blob/main/spatial/geometry_utils.py): `spatial/geometry_utils.py`
- [Vehicle counts](https://github.com/hploc17/edge-ai/blob/main/analytics/presence_counter.py): `analytics/presence_counter.py`
- [Speed estimates](https://github.com/hploc17/edge-ai/blob/main/analytics/speed_estimator.py): `analytics/speed_estimator.py`
- [Traffic classification](https://github.com/hploc17/edge-ai/blob/main/analytics/traffic_classifier.py): `analytics/traffic_classifier.py`

### Snapshot delivery

- [Snapshot service](https://github.com/hploc17/edge-ai/blob/main/snap/snapshot_service.py): `snap/snapshot_service.py`
- [Offline outbox](https://github.com/hploc17/edge-ai/blob/main/snap/outbox.py): `snap/outbox.py`

### Edge communications

- [Edge MQTT client](https://github.com/hploc17/edge-ai/blob/main/communication/mqtt_client.py): `communication/mqtt_client.py`
- [Command router](https://github.com/hploc17/edge-ai/blob/main/communication/command_router.py): `communication/command_router.py`
- [System metrics](https://github.com/hploc17/edge-ai/blob/main/communication/system_metrics.py): `communication/system_metrics.py`

### WebGIS backend

- [Backend API](https://github.com/hploc17/edge-ai/blob/main/webgis/backend/main.py): `webgis/backend/main.py`
- [API routers](https://github.com/hploc17/edge-ai/tree/main/webgis/backend/routers): `webgis/backend/routers`
- [Backend MQTT service](https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/mqtt_service.py): `webgis/backend/services/mqtt_service.py`
- [Node data store](https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/data_store.py): `webgis/backend/services/data_store.py`
- [WebSocket manager](https://github.com/hploc17/edge-ai/blob/main/webgis/backend/services/websocket_manager.py): `webgis/backend/services/websocket_manager.py`

### WebGIS frontend

- [WebGIS application](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/App.tsx): `webgis/frontend/src/App.tsx`
- [Frontend API client](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/services/api.ts): `webgis/frontend/src/services/api.ts`
- [Frontend WebSocket](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/services/websocket.ts): `webgis/frontend/src/services/websocket.ts`
- [Traffic map](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/Map/WebGISMap.tsx): `webgis/frontend/src/components/Map/WebGISMap.tsx`
- [Fleet management](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/Fleet/NodeManagementPanel.tsx): `webgis/frontend/src/components/Fleet/NodeManagementPanel.tsx`
- [Congestion history](https://github.com/hploc17/edge-ai/blob/main/webgis/frontend/src/components/History/CongestionHistoryModal.tsx): `webgis/frontend/src/components/History/CongestionHistoryModal.tsx`

### Other components

- **Operator**
- **Video source**
- **MQTT broker**
- **Snapshot API**

## Connections

- Video source → GStreamer pipeline: supplies frames
- Edge orchestrator → GStreamer pipeline: builds pipeline
- Edge orchestrator → ROI management: loads ROI
- ROI management → ROI geometry: uses geometry
- Edge orchestrator → Vehicle counts: computes counts
- Edge orchestrator → Speed estimates: estimates speed
- Edge orchestrator → Traffic classification: classifies traffic
- Edge orchestrator → Snapshot service: starts and updates
- Edge orchestrator → Edge MQTT client: publishes telemetry
- Edge orchestrator → Command router: routes commands
- Edge orchestrator → System metrics: collects metrics
- Snapshot service → Offline outbox: stores pending images
- Snapshot service → Snapshot API: uploads snapshots
- Edge MQTT client → MQTT broker: publishes and subscribes
- MQTT broker → Backend MQTT service: forwards telemetry and commands
- Backend MQTT service → Node data store: updates node state
- Backend MQTT service → WebSocket manager: broadcasts updates
- Backend MQTT service → MQTT broker: publishes commands
- Edge MQTT client → Command router: dispatches commands
- Command router → Edge MQTT client: reports command results
- Backend API → Backend MQTT service: starts service
- Backend API → WebSocket manager: serves WebSocket
- Backend API → API routers: registers routes
- Operator → WebGIS application: uses WebGIS
- WebGIS application → Frontend API client: requests data
- Frontend API client → API routers: calls API
- WebGIS application → Frontend WebSocket: receives live updates
- Frontend WebSocket → WebSocket manager: connects and receives
- WebGIS application → Traffic map: renders map
- WebGIS application → Fleet management: opens fleet tools
- WebGIS application → Congestion history: opens history