# krekker0101/rohai architecture

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

- Interactive diagram: https://gitdiagram.com/krekker0101/rohai
- Repository: https://github.com/krekker0101/rohai

## Overview

Smart Traffic AI combines a traffic-control backend, deterministic simulation, camera-based vision, and an operator dashboard. The principal loop advances simulated or observed traffic, computes a desired signal (including emergency priority), applies safety constraints, and exposes telemetry to the dashboard. The separate vision path captures frames, detects and analyzes traffic using camera geometry, then supplies observed state and video overlays. The README documents the major capabilities; some subsystem links below rely on that documentation or the SOURCE INDEX because their implementation excerpts were not provided.

Main entry points: [`packages/vision/src/traffic_vision/pipeline.py`](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/pipeline.py) (Vision pipeline), [`packages/simulator/src/traffic_simulator/engine.py`](https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/engine.py) (Simulation engine), [`apps/backend/src/smart_traffic_backend/main.py`](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/main.py) (HTTP and WebSocket API), [`apps/backend/src/smart_traffic_backend/vision_runtime.py`](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/vision_runtime.py) (Vision runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Traffic control"]
  node_traffic_controller["Phase controller<br/>[controller.py]"]
  node_observed_controller["Observed controller"]
  node_safety["Safety state machine<br/>[safety.py]"]
  node_core_models["Traffic state models<br/>[models.py]"]
end

subgraph group_vision["Vision pipeline"]
  node_video_sources["Video sources<br/>[sources.py]"]
  node_detector["YOLO detector<br/>[detector.py]"]
  node_vision_pipeline["Vision pipeline<br/>[pipeline.py]"]
  node_geometry["Camera geometry<br/>[geometry.py]"]
  node_analytics["Traffic analytics<br/>[analytics.py]"]
  node_vision_models["Detection and track models<br/>[models.py]"]
  node_overlay["Video overlay<br/>[overlay.py]"]
end

subgraph group_backend["Backend runtime"]
  node_backend_api["HTTP and WebSocket API<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_runtime["Simulation runtime<br/>[runtime.py]"]
  node_demo_runtime["Demo runtime<br/>[demo_runtime.py]"]
  node_vision_runtime["Vision runtime<br/>[vision_runtime.py]"]
  node_hardware["Hardware adapter<br/>[hardware.py]"]
end

subgraph group_dashboard["Operator dashboard"]
  node_dashboard_app["Dashboard app<br/>[App.tsx]"]
  node_dashboard_views["Traffic views<br/>[Overview.tsx]"]
  node_dashboard_features["Analytics and controls<br/>[Analytics.tsx]"]
  node_api_client["REST client<br/>[api.ts]"]
  node_telemetry_model["Telemetry normalization<br/>[telemetry.ts]"]
end

subgraph group_simulation["Simulation and metrics"]
  node_sim_engine["Simulation engine<br/>[engine.py]"]
  node_queue_sim["Queue simulator<br/>[simulator.py]"]
  node_comparison["KPI comparison<br/>[comparison.py]"]
end

node_operator(("Operator"))
node_camera(("Camera or video source"))
node_hardware_device["ESP32 hardware"]

node_operator -->|"operates"| node_dashboard_app
node_dashboard_app -->|"renders"| node_dashboard_views
node_dashboard_app -->|"offers"| node_dashboard_features
node_dashboard_features -->|"requests data"| node_api_client
node_dashboard_app -->|"requests data"| node_api_client
node_dashboard_views -->|"uses"| node_telemetry_model
node_api_client -->|"calls REST"| node_backend_api
node_backend_api -->|"drives"| node_runtime
node_backend_api -->|"serves demo"| node_demo_runtime
node_backend_api -->|"serves vision"| node_vision_runtime
node_config -->|"configures"| node_runtime
node_config -->|"configures"| node_vision_runtime
node_runtime -->|"advances"| node_sim_engine
node_runtime -->|"applies signals"| node_hardware
node_demo_runtime -->|"advances"| node_sim_engine
node_sim_engine -->|"advances queues"| node_queue_sim
node_sim_engine -->|"requests decisions"| node_traffic_controller
node_sim_engine -->|"advances safety"| node_safety
node_traffic_controller -->|"uses types"| node_core_models
node_observed_controller -->|"delegates policy"| node_traffic_controller
node_observed_controller -->|"advances safety"| node_safety
node_vision_runtime -->|"runs"| node_vision_pipeline
node_vision_runtime -->|"controls observed state"| node_observed_controller
node_video_sources -->|"provides frames"| node_vision_pipeline
node_camera -->|"supplies video"| node_video_sources
node_vision_pipeline -->|"infers detections"| node_detector
node_vision_pipeline -->|"analyzes detections"| node_analytics
node_vision_pipeline -->|"renders frames"| node_overlay
node_analytics -.->|"uses calibration"| node_geometry
node_vision_pipeline -->|"publishes results"| node_vision_models
node_vision_runtime -->|"produces traffic state"| node_core_models
node_backend_api -->|"streams telemetry"| node_dashboard_app
node_comparison -->|"benchmarks"| node_sim_engine
node_hardware -.->|"optional connection"| node_hardware_device

click node_dashboard_app "https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/App.tsx"
click node_dashboard_views "https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/components/Overview.tsx"
click node_dashboard_features "https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/features/Analytics.tsx"
click node_api_client "https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/data/api.ts"
click node_telemetry_model "https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/domain/telemetry.ts"
click node_backend_api "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/main.py"
click node_config "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/config.py"
click node_runtime "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/runtime.py"
click node_demo_runtime "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/demo_runtime.py"
click node_vision_runtime "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/vision_runtime.py"
click node_hardware "https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/hardware.py"
click node_sim_engine "https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/engine.py"
click node_queue_sim "https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/simulator.py"
click node_comparison "https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/comparison.py"
click node_traffic_controller "https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/controller.py"
click node_observed_controller "https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/observed_controller.py"
click node_safety "https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/safety.py"
click node_core_models "https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/models.py"
click node_video_sources "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/sources.py"
click node_detector "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/detector.py"
click node_vision_pipeline "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/pipeline.py"
click node_geometry "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/geometry.py"
click node_analytics "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/analytics.py"
click node_vision_models "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/models.py"
click node_overlay "https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/overlay.py"

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_traffic_controller,node_observed_controller,node_safety,node_core_models toneBlue
class node_video_sources,node_detector,node_vision_pipeline,node_geometry,node_analytics,node_vision_models,node_overlay toneAmber
class node_backend_api,node_config,node_runtime,node_demo_runtime,node_vision_runtime,node_hardware toneMint
class node_dashboard_app,node_dashboard_views,node_dashboard_features,node_api_client,node_telemetry_model toneRose
class node_sim_engine,node_queue_sim,node_comparison,node_operator,node_camera,node_hardware_device toneIndigo
```

## Components

### Traffic control

- [Phase controller](https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/controller.py): `packages/traffic_core/src/traffic_core/controller.py`
- [Observed controller](https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/observed_controller.py): `packages/traffic_core/src/traffic_core/observed_controller.py`
- [Safety state machine](https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/safety.py): `packages/traffic_core/src/traffic_core/safety.py`
- [Traffic state models](https://github.com/krekker0101/rohai/blob/main/packages/traffic_core/src/traffic_core/models.py): `packages/traffic_core/src/traffic_core/models.py`

### Vision pipeline

- [Video sources](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/sources.py): `packages/vision/src/traffic_vision/sources.py`
- [YOLO detector](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/detector.py): `packages/vision/src/traffic_vision/detector.py`
- [Vision pipeline](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/pipeline.py): `packages/vision/src/traffic_vision/pipeline.py`
- [Camera geometry](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/geometry.py): `packages/vision/src/traffic_vision/geometry.py`
- [Traffic analytics](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/analytics.py): `packages/vision/src/traffic_vision/analytics.py`
- [Detection and track models](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/models.py): `packages/vision/src/traffic_vision/models.py`
- [Video overlay](https://github.com/krekker0101/rohai/blob/main/packages/vision/src/traffic_vision/overlay.py): `packages/vision/src/traffic_vision/overlay.py`

### Backend runtime

- [HTTP and WebSocket API](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/main.py): `apps/backend/src/smart_traffic_backend/main.py`
- [Runtime settings](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/config.py): `apps/backend/src/smart_traffic_backend/config.py`
- [Simulation runtime](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/runtime.py): `apps/backend/src/smart_traffic_backend/runtime.py`
- [Demo runtime](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/demo_runtime.py): `apps/backend/src/smart_traffic_backend/demo_runtime.py`
- [Vision runtime](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/vision_runtime.py): `apps/backend/src/smart_traffic_backend/vision_runtime.py`
- [Hardware adapter](https://github.com/krekker0101/rohai/blob/main/apps/backend/src/smart_traffic_backend/hardware.py): `apps/backend/src/smart_traffic_backend/hardware.py`

### Operator dashboard

- [Dashboard app](https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/App.tsx): `apps/dashboard/src/App.tsx`
- [Traffic views](https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/components/Overview.tsx): `apps/dashboard/src/components/Overview.tsx`
- [Analytics and controls](https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/features/Analytics.tsx): `apps/dashboard/src/features/Analytics.tsx`
- [REST client](https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/data/api.ts): `apps/dashboard/src/data/api.ts`
- [Telemetry normalization](https://github.com/krekker0101/rohai/blob/main/apps/dashboard/src/domain/telemetry.ts): `apps/dashboard/src/domain/telemetry.ts`

### Simulation and metrics

- [Simulation engine](https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/engine.py): `packages/simulator/src/traffic_simulator/engine.py`
- [Queue simulator](https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/simulator.py): `packages/simulator/src/traffic_simulator/simulator.py`
- [KPI comparison](https://github.com/krekker0101/rohai/blob/main/packages/simulator/src/traffic_simulator/comparison.py): `packages/simulator/src/traffic_simulator/comparison.py`

### Other components

- **Operator**
- **Camera or video source**
- **ESP32 hardware**

## Connections

- Operator → Dashboard app: operates
- Dashboard app → Traffic views: renders (evidence: `apps/dashboard/src/App.tsx`)
- Dashboard app → Analytics and controls: offers (evidence: `apps/dashboard/src/App.tsx`)
- Analytics and controls → REST client: requests data
- Dashboard app → REST client: requests data (evidence: `apps/dashboard/src/App.tsx`)
- Traffic views → Telemetry normalization: uses (evidence: `apps/dashboard/src/components/Overview.tsx`)
- REST client → HTTP and WebSocket API: calls REST
- HTTP and WebSocket API → Simulation runtime: drives (evidence: `apps/backend/src/smart_traffic_backend/main.py`)
- HTTP and WebSocket API → Demo runtime: serves demo (evidence: `apps/backend/src/smart_traffic_backend/main.py`)
- HTTP and WebSocket API → Vision runtime: serves vision (evidence: `apps/backend/src/smart_traffic_backend/main.py`)
- Runtime settings → Simulation runtime: configures (evidence: `apps/backend/src/smart_traffic_backend/config.py`)
- Runtime settings → Vision runtime: configures (evidence: `apps/backend/src/smart_traffic_backend/config.py`)
- Simulation runtime → Simulation engine: advances (evidence: `apps/backend/src/smart_traffic_backend/runtime.py`)
- Simulation runtime → Hardware adapter: applies signals
- Demo runtime → Simulation engine: advances (evidence: `apps/backend/src/smart_traffic_backend/demo_runtime.py`)
- Simulation engine → Queue simulator: advances queues (evidence: `packages/simulator/src/traffic_simulator/engine.py`)
- Simulation engine → Phase controller: requests decisions (evidence: `packages/simulator/src/traffic_simulator/engine.py`)
- Simulation engine → Safety state machine: advances safety (evidence: `packages/simulator/src/traffic_simulator/engine.py`)
- Phase controller → Traffic state models: uses types (evidence: `packages/traffic_core/src/traffic_core/controller.py`)
- Observed controller → Phase controller: delegates policy (evidence: `packages/traffic_core/src/traffic_core/observed_controller.py`)
- Observed controller → Safety state machine: advances safety (evidence: `packages/traffic_core/src/traffic_core/observed_controller.py`)
- Vision runtime → Vision pipeline: runs (evidence: `apps/backend/src/smart_traffic_backend/vision_runtime.py`)
- Vision runtime → Observed controller: controls observed state (evidence: `apps/backend/src/smart_traffic_backend/vision_runtime.py`)
- Video sources → Vision pipeline: provides frames (evidence: `packages/vision/src/traffic_vision/pipeline.py`)
- Camera or video source → Video sources: supplies video
- Vision pipeline → YOLO detector: infers detections (evidence: `packages/vision/src/traffic_vision/pipeline.py`)
- Vision pipeline → Traffic analytics: analyzes detections (evidence: `packages/vision/src/traffic_vision/pipeline.py`)
- Vision pipeline → Video overlay: renders frames (evidence: `packages/vision/src/traffic_vision/pipeline.py`)
- Traffic analytics → Camera geometry: uses calibration (evidence: `packages/vision/src/traffic_vision/analytics.py`)
- Vision pipeline → Detection and track models: publishes results (evidence: `packages/vision/src/traffic_vision/pipeline.py`)
- Vision runtime → Traffic state models: produces traffic state (evidence: `apps/backend/src/smart_traffic_backend/vision_runtime.py`)
- HTTP and WebSocket API → Dashboard app: streams telemetry
- KPI comparison → Simulation engine: benchmarks (evidence: `packages/simulator/src/traffic_simulator/comparison.py`)
- Hardware adapter → ESP32 hardware: optional connection
