# linh-nguyen123/urbanvibe-mlai2026 architecture

> Architecture diagram of the GitHub repository linh-nguyen123/urbanvibe-mlai2026, 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/linh-nguyen123/urbanvibe-mlai2026
- Repository: https://github.com/linh-nguyen123/urbanvibe-mlai2026

## Overview

UrbanVibe: SafeRoute combines pre-trip acoustic-risk route decisions with an on-trip, on-device hazard monitor. A rider chooses a route in the Streamlit app; the app requests a decision, presents route trade-offs, and supports confirmation. During travel, the app starts microphone capture; the engine analyzes audio and can trigger haptic alerts. The README documents Pareto/MCDA/XAI decisions and offline edge-AI monitoring. The excerpts show the main engine flow; map routing inputs and some UI integrations are only partly sampled, so those links are limited to documented or indexed evidence.

Main entry points: [`ui/app.py`](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/ui/app.py) (Trip dashboard), [`engine/main_engine.py`](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/main_engine.py) (Audio engine coordinator), [`engine/decision_engine.py`](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/decision_engine.py) (Route decision engine), [`engine/model_inference.py`](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/model_inference.py) (YAMNet inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product_ui["Rider experience"]
  node_streamlit_app["Trip dashboard<br/>[app.py]"]
  node_mock_engine["Demo engine<br/>[mock_engine.py]"]
end

subgraph group_trip_decisions["Pre-trip decisions"]
  node_decision_engine["Route decision engine<br/>[decision_engine.py]"]
  node_route_scenarios["Route scenarios<br/>[data_contract.py]"]
end

subgraph group_edge_safety["On-trip edge safety"]
  node_main_engine["Audio engine coordinator<br/>[main_engine.py]"]
  node_audio_stream["Audio capture buffer<br/>[audio_stream.py]"]
  node_model_inference["YAMNet inference<br/>[model_inference.py]"]
  node_dsp["Signal analysis<br/>[dsp_filter.py]"]
  node_yamnet_models["YAMNet model assets<br/>[yamnet.tflite]"]
  node_haptic["Haptic controller"]
end

subgraph group_contracts["Shared data"]
  node_data_contract["Shared data contracts<br/>[data_contract.py]"]
end

node_rider(("Rider"))
node_osm["OpenStreetMap service"]
node_microphone["Device microphone"]

node_rider -->|"sets trip"| node_streamlit_app
node_streamlit_app -->|"requests plan"| node_decision_engine
node_decision_engine -->|"evaluates routes"| node_route_scenarios
node_decision_engine -->|"returns decision"| node_data_contract
node_streamlit_app -->|"geocodes places"| node_osm
node_streamlit_app -->|"uses demo data"| node_mock_engine
node_rider -->|"starts monitoring"| node_streamlit_app
node_streamlit_app -->|"starts stream"| node_main_engine
node_main_engine -->|"captures windows"| node_audio_stream
node_microphone -.->|"provides audio"| node_audio_stream
node_main_engine -->|"infers hazards"| node_model_inference
node_model_inference -->|"analyzes signal"| node_dsp
node_model_inference -->|"loads model"| node_yamnet_models
node_main_engine -->|"triggers alert"| node_haptic
node_main_engine -->|"builds payload"| node_data_contract
node_streamlit_app -->|"renders payloads"| node_data_contract

click node_streamlit_app "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/ui/app.py"
click node_mock_engine "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/ui/mock_engine.py"
click node_decision_engine "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/decision_engine.py"
click node_route_scenarios "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/data_contract.py"
click node_data_contract "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/data_contract.py"
click node_main_engine "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/main_engine.py"
click node_audio_stream "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/audio_stream.py"
click node_model_inference "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/model_inference.py"
click node_dsp "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/dsp_filter.py"
click node_yamnet_models "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/models/yamnet.tflite"
click node_haptic "https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/haptic_controller.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_streamlit_app,node_mock_engine toneBlue
class node_decision_engine,node_route_scenarios toneAmber
class node_main_engine,node_audio_stream,node_model_inference,node_dsp,node_yamnet_models,node_haptic toneMint
class node_data_contract toneRose
class node_rider,node_osm,node_microphone toneIndigo
```

## Components

### Rider experience

- [Trip dashboard](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/ui/app.py): `ui/app.py`
- [Demo engine](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/ui/mock_engine.py): `ui/mock_engine.py`

### Pre-trip decisions

- [Route decision engine](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/decision_engine.py): `engine/decision_engine.py`
- [Route scenarios](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/data_contract.py): `data_contract.py`

### On-trip edge safety

- [Audio engine coordinator](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/main_engine.py): `engine/main_engine.py`
- [Audio capture buffer](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/audio_stream.py): `engine/audio_stream.py`
- [YAMNet inference](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/model_inference.py): `engine/model_inference.py`
- [Signal analysis](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/dsp_filter.py): `engine/dsp_filter.py`
- [YAMNet model assets](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/models/yamnet.tflite): `engine/models/yamnet.tflite`
- [Haptic controller](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/engine/haptic_controller.py): `engine/haptic_controller.py`

### Shared data

- [Shared data contracts](https://github.com/linh-nguyen123/urbanvibe-mlai2026/blob/main/data_contract.py): `data_contract.py`

### Other components

- **Rider**
- **OpenStreetMap service**
- **Device microphone**

## Connections

- Rider → Trip dashboard: sets trip (evidence: `ui/app.py`)
- Trip dashboard → Route decision engine: requests plan (evidence: `ui/app.py`)
- Route decision engine → Route scenarios: evaluates routes (evidence: `engine/decision_engine.py`)
- Route decision engine → Shared data contracts: returns decision (evidence: `engine/decision_engine.py`)
- Trip dashboard → OpenStreetMap service: geocodes places (evidence: `ui/app.py`)
- Trip dashboard → Demo engine: uses demo data (evidence: `ui/app.py`)
- Rider → Trip dashboard: starts monitoring (evidence: `ui/app.py`)
- Trip dashboard → Audio engine coordinator: starts stream (evidence: `ui/app.py`)
- Audio engine coordinator → Audio capture buffer: captures windows (evidence: `engine/main_engine.py`)
- Device microphone → Audio capture buffer: provides audio (evidence: `engine/audio_stream.py`)
- Audio engine coordinator → YAMNet inference: infers hazards (evidence: `engine/main_engine.py`)
- YAMNet inference → Signal analysis: analyzes signal (evidence: `engine/model_inference.py`)
- YAMNet inference → YAMNet model assets: loads model (evidence: `engine/model_inference.py`)
- Audio engine coordinator → Haptic controller: triggers alert (evidence: `engine/main_engine.py`)
- Audio engine coordinator → Shared data contracts: builds payload (evidence: `engine/main_engine.py`)
- Trip dashboard → Shared data contracts: renders payloads (evidence: `ui/app.py`)
