# harshi-max/roadvision architecture

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

- Interactive diagram: https://gitdiagram.com/harshi-max/roadvision
- Repository: https://github.com/harshi-max/roadvision

## Overview

RoadVision is a Streamlit pothole-detection app backed by a small road-defect processing package. Its implemented upload workflow reads video frames, optionally preprocesses them, invokes YOLO tracking, estimates severity, updates track and incident records, and produces an annotated video plus performance metrics. The README documents broader image, live-stream, mapping, export and reporting capabilities; some are not wired in the sampled UI. Edges reflect shown calls or README-described flows, not assumed integrations.

Main entry points: [`ui.py`](https://github.com/harshi-max/roadvision/blob/main/ui.py) (Streamlit workflow), [`roadvision/incidents/incident_manager.py`](https://github.com/harshi-max/roadvision/blob/main/roadvision/incidents/incident_manager.py) (Incident management), [`roadvision`](https://github.com/harshi-max/roadvision/tree/main/roadvision) (Analytics and exports), [`roadvision/reporting/report_generator.py`](https://github.com/harshi-max/roadvision/blob/main/roadvision/reporting/report_generator.py) (Incident reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Streamlit workflow<br/>[ui.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_processing["Detection processing"]
  node_media["Media input<br/>[ui.py]"]
  node_model["YOLO detector and tracker<br/>[ui.py]"]
  node_preprocess["Frame preprocessing<br/>[preprocessor.py]"]
  node_track[("Track records<br/>[track_manager.py]")]
  node_severity["Severity estimation"]
end

subgraph group_domain["Incident services"]
  node_incidents[("Incident management")]
  node_ocr["Frame OCR<br/>[ocr_service.py]"]
  node_performance["Performance metrics"]
  node_location["Location providers"]
  node_authority["Authority routing"]
end

subgraph group_outputs["Results and integrations"]
  node_report["Incident reports"]
  node_notifications["Notifications"]
  node_video["Annotated video<br/>[ui.py]"]
  node_analytics["Analytics and exports"]
  node_map["GPS map view"]
end

node_user(("Road inspector"))

node_user -->|"configures and starts"| node_ui
node_ui -->|"loads settings"| node_config
node_ui -->|"accepts upload"| node_media
node_ui -->|"tracks frames"| node_model
node_ui -->|"preprocesses frames"| node_preprocess
node_ui -->|"updates tracks"| node_track
node_ui -->|"estimates severity"| node_severity
node_ui -->|"records detections"| node_incidents
node_ui -->|"samples frames"| node_ocr
node_ui -->|"records timing"| node_performance
node_ui -->|"writes annotated frames"| node_video
node_ui -.->|"aggregates detections"| node_analytics
node_analytics -.->|"plots GPS data"| node_map
node_analytics -.->|"exports reports"| node_report
node_incidents -.->|"generates incident report"| node_report
node_incidents -.->|"resolves responsible authority"| node_authority
node_incidents -.->|"triggers notification"| node_notifications
node_location -.->|"supplies coordinates"| node_map

click node_ui "https://github.com/harshi-max/roadvision/blob/main/ui.py"
click node_config "https://github.com/harshi-max/roadvision/blob/main/roadvision/config.py"
click node_media "https://github.com/harshi-max/roadvision/blob/main/ui.py"
click node_model "https://github.com/harshi-max/roadvision/blob/main/ui.py"
click node_preprocess "https://github.com/harshi-max/roadvision/blob/main/roadvision/preprocessing/preprocessor.py"
click node_track "https://github.com/harshi-max/roadvision/blob/main/roadvision/tracking/track_manager.py"
click node_severity "https://github.com/harshi-max/roadvision/blob/main/roadvision/severity/severity_estimator.py"
click node_incidents "https://github.com/harshi-max/roadvision/blob/main/roadvision/incidents/incident_manager.py"
click node_ocr "https://github.com/harshi-max/roadvision/blob/main/roadvision/ocr/ocr_service.py"
click node_performance "https://github.com/harshi-max/roadvision/blob/main/roadvision/performance/performance_monitor.py"
click node_location "https://github.com/harshi-max/roadvision/blob/main/roadvision/location/location_provider.py"
click node_authority "https://github.com/harshi-max/roadvision/blob/main/roadvision/authority/authority_router.py"
click node_report "https://github.com/harshi-max/roadvision/blob/main/roadvision/reporting/report_generator.py"
click node_notifications "https://github.com/harshi-max/roadvision/blob/main/roadvision/notifications/notification_service.py"
click node_video "https://github.com/harshi-max/roadvision/blob/main/ui.py"
click node_analytics "https://github.com/harshi-max/roadvision/tree/main/roadvision"
click node_map "https://github.com/harshi-max/roadvision/tree/main/roadvision"

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_ui,node_config toneBlue
class node_media,node_model,node_preprocess,node_track,node_severity toneAmber
class node_incidents,node_ocr,node_performance,node_location,node_authority toneMint
class node_report,node_notifications,node_video,node_analytics,node_map toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Streamlit workflow](https://github.com/harshi-max/roadvision/blob/main/ui.py): `ui.py`
- [Configuration](https://github.com/harshi-max/roadvision/blob/main/roadvision/config.py): `roadvision/config.py`

### Detection processing

- [Media input](https://github.com/harshi-max/roadvision/blob/main/ui.py): `ui.py`
- [YOLO detector and tracker](https://github.com/harshi-max/roadvision/blob/main/ui.py): `ui.py`
- [Frame preprocessing](https://github.com/harshi-max/roadvision/blob/main/roadvision/preprocessing/preprocessor.py): `roadvision/preprocessing/preprocessor.py`
- [Track records](https://github.com/harshi-max/roadvision/blob/main/roadvision/tracking/track_manager.py): `roadvision/tracking/track_manager.py`
- [Severity estimation](https://github.com/harshi-max/roadvision/blob/main/roadvision/severity/severity_estimator.py): `roadvision/severity/severity_estimator.py`

### Incident services

- [Incident management](https://github.com/harshi-max/roadvision/blob/main/roadvision/incidents/incident_manager.py): `roadvision/incidents/incident_manager.py`
- [Frame OCR](https://github.com/harshi-max/roadvision/blob/main/roadvision/ocr/ocr_service.py): `roadvision/ocr/ocr_service.py`
- [Performance metrics](https://github.com/harshi-max/roadvision/blob/main/roadvision/performance/performance_monitor.py): `roadvision/performance/performance_monitor.py`
- [Location providers](https://github.com/harshi-max/roadvision/blob/main/roadvision/location/location_provider.py): `roadvision/location/location_provider.py`
- [Authority routing](https://github.com/harshi-max/roadvision/blob/main/roadvision/authority/authority_router.py): `roadvision/authority/authority_router.py`

### Results and integrations

- [Incident reports](https://github.com/harshi-max/roadvision/blob/main/roadvision/reporting/report_generator.py): `roadvision/reporting/report_generator.py`
- [Notifications](https://github.com/harshi-max/roadvision/blob/main/roadvision/notifications/notification_service.py): `roadvision/notifications/notification_service.py`
- [Annotated video](https://github.com/harshi-max/roadvision/blob/main/ui.py): `ui.py`
- [Analytics and exports](https://github.com/harshi-max/roadvision/tree/main/roadvision): `roadvision`
- [GPS map view](https://github.com/harshi-max/roadvision/tree/main/roadvision): `roadvision`

### Other components

- **Road inspector**

## Connections

- Road inspector → Streamlit workflow: configures and starts (evidence: `readme.md`)
- Streamlit workflow → Configuration: loads settings (evidence: `ui.py`)
- Streamlit workflow → Media input: accepts upload (evidence: `ui.py`)
- Streamlit workflow → YOLO detector and tracker: tracks frames (evidence: `ui.py`)
- Streamlit workflow → Frame preprocessing: preprocesses frames (evidence: `ui.py`)
- Streamlit workflow → Track records: updates tracks (evidence: `ui.py`)
- Streamlit workflow → Severity estimation: estimates severity (evidence: `ui.py`)
- Streamlit workflow → Incident management: records detections (evidence: `ui.py`)
- Streamlit workflow → Frame OCR: samples frames (evidence: `ui.py`)
- Streamlit workflow → Performance metrics: records timing (evidence: `ui.py`)
- Streamlit workflow → Annotated video: writes annotated frames (evidence: `ui.py`)
- Streamlit workflow → Analytics and exports: aggregates detections (evidence: `readme.md`)
- Analytics and exports → GPS map view: plots GPS data (evidence: `readme.md`)
- Analytics and exports → Incident reports: exports reports (evidence: `readme.md`)
- Incident management → Incident reports: generates incident report
- Incident management → Authority routing: resolves responsible authority
- Incident management → Notifications: triggers notification
- Location providers → GPS map view: supplies coordinates (evidence: `roadvision/location/__init__.py`)