# polisetti-bharath/roadshield architecture

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

- Interactive diagram: https://gitdiagram.com/polisetti-bharath/roadshield
- Repository: https://github.com/polisetti-bharath/roadshield

## Overview

RoadShield is a Streamlit road-damage inspection app: users choose live camera, image, or video input; YOLOv8 detects and labels damage, and image/video pothole detections can be turned into location-aware reports. The repository also includes a dataset-preparation, model-training, and evaluation workflow. Page-to-helper links and image/video inference are visible in excerpts; the realtime page and notebook internals were not sampled, so their details are limited to documented capabilities.

Main entry points: [`sample_utils/report.py`](https://github.com/polisetti-bharath/roadshield/blob/main/sample_utils/report.py) (Report helpers), [`pages/2_Image Detection.py`](https://github.com/polisetti-bharath/roadshield/blob/main/pages/2_Image%20Detection.py) (Image detection), [`pages/3_Video Detection.py`](https://github.com/polisetti-bharath/roadshield/blob/main/pages/3_Video%20Detection.py) (Video detection), [`models/YOLOv8_Small_RDD.pt`](https://github.com/polisetti-bharath/roadshield/blob/main/models/YOLOv8_Small_RDD.pt) (YOLOv8 weights)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Inspection app"]
  node_home["Home screen<br/>[Home.py]"]
  node_realtime["Live detection"]
  node_image["Image detection"]
  node_video["Video detection"]
  node_weights["YOLOv8 weights"]
  node_shared_ui["Shared UI<br/>[ui.py]"]
end

subgraph group_reporting["Damage reporting"]
  node_report_helpers["Report helpers<br/>[report.py]"]
  node_contact_file[("Saved contacts")]
  node_geolocation["Browser geolocation"]
  node_nominatim["Nominatim"]
  node_authorities["Authority channels"]
end

subgraph group_training["Model development"]
  node_crddc["CRDDC2022 data"]
  node_prepare["Dataset preparation"]
  node_train["Model training"]
  node_evaluate["Evaluation"]
end

node_inspector(("Inspector"))

node_inspector -->|"opens app"| node_home
node_inspector -->|"chooses live mode"| node_realtime
node_inspector -->|"chooses image mode"| node_image
node_inspector -->|"chooses video mode"| node_video
node_home -->|"renders with"| node_shared_ui
node_image -->|"renders with"| node_shared_ui
node_video -->|"renders with"| node_shared_ui
node_image -->|"loads model"| node_weights
node_video -->|"loads model"| node_weights
node_realtime -.->|"uses model"| node_weights
node_image -->|"calls reporting"| node_report_helpers
node_video -->|"calls reporting"| node_report_helpers
node_report_helpers -->|"reads and writes"| node_contact_file
node_report_helpers -->|"requests location"| node_geolocation
node_report_helpers -->|"reverse geocodes"| node_nominatim
node_report_helpers -->|"prepares report channels"| node_authorities
node_crddc -->|"provides dataset"| node_prepare
node_prepare -->|"prepares data for"| node_train
node_train -->|"model evaluated by"| node_evaluate

click node_home "https://github.com/polisetti-bharath/roadshield/blob/main/Home.py"
click node_realtime "https://github.com/polisetti-bharath/roadshield/blob/main/pages/1_Realtime%20Detection.py"
click node_image "https://github.com/polisetti-bharath/roadshield/blob/main/pages/2_Image%20Detection.py"
click node_video "https://github.com/polisetti-bharath/roadshield/blob/main/pages/3_Video%20Detection.py"
click node_weights "https://github.com/polisetti-bharath/roadshield/blob/main/models/YOLOv8_Small_RDD.pt"
click node_shared_ui "https://github.com/polisetti-bharath/roadshield/blob/main/sample_utils/ui.py"
click node_report_helpers "https://github.com/polisetti-bharath/roadshield/blob/main/sample_utils/report.py"
click node_prepare "https://github.com/polisetti-bharath/roadshield/blob/main/training/0_PrepareDatasetYOLOv8.ipynb"
click node_train "https://github.com/polisetti-bharath/roadshield/blob/main/training/1_TrainingYOLOv8.ipynb"
click node_evaluate "https://github.com/polisetti-bharath/roadshield/blob/main/training/2_EvaluationTesting.ipynb"

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_home,node_realtime,node_image,node_video,node_weights,node_shared_ui toneBlue
class node_report_helpers,node_contact_file,node_geolocation,node_nominatim,node_authorities toneAmber
class node_crddc,node_prepare,node_train,node_evaluate toneMint
class node_inspector toneIndigo
```

## Components

### Inspection app

- [Home screen](https://github.com/polisetti-bharath/roadshield/blob/main/Home.py): `Home.py`
- [Live detection](https://github.com/polisetti-bharath/roadshield/blob/main/pages/1_Realtime%20Detection.py): `pages/1_Realtime Detection.py`
- [Image detection](https://github.com/polisetti-bharath/roadshield/blob/main/pages/2_Image%20Detection.py): `pages/2_Image Detection.py`
- [Video detection](https://github.com/polisetti-bharath/roadshield/blob/main/pages/3_Video%20Detection.py): `pages/3_Video Detection.py`
- [YOLOv8 weights](https://github.com/polisetti-bharath/roadshield/blob/main/models/YOLOv8_Small_RDD.pt): `models/YOLOv8_Small_RDD.pt`
- [Shared UI](https://github.com/polisetti-bharath/roadshield/blob/main/sample_utils/ui.py): `sample_utils/ui.py`

### Damage reporting

- [Report helpers](https://github.com/polisetti-bharath/roadshield/blob/main/sample_utils/report.py): `sample_utils/report.py`
- **Saved contacts**
- **Browser geolocation**
- **Nominatim**
- **Authority channels**

### Model development

- **CRDDC2022 data**
- [Dataset preparation](https://github.com/polisetti-bharath/roadshield/blob/main/training/0_PrepareDatasetYOLOv8.ipynb): `training/0_PrepareDatasetYOLOv8.ipynb`
- [Model training](https://github.com/polisetti-bharath/roadshield/blob/main/training/1_TrainingYOLOv8.ipynb): `training/1_TrainingYOLOv8.ipynb`
- [Evaluation](https://github.com/polisetti-bharath/roadshield/blob/main/training/2_EvaluationTesting.ipynb): `training/2_EvaluationTesting.ipynb`

### Other components

- **Inspector**

## Connections

- Inspector → Home screen: opens app (evidence: `README.md`)
- Inspector → Live detection: chooses live mode
- Inspector → Image detection: chooses image mode
- Inspector → Video detection: chooses video mode
- Home screen → Shared UI: renders with (evidence: `Home.py`)
- Image detection → Shared UI: renders with (evidence: `pages/2_Image Detection.py`)
- Video detection → Shared UI: renders with (evidence: `pages/3_Video Detection.py`)
- Image detection → YOLOv8 weights: loads model (evidence: `pages/2_Image Detection.py`)
- Video detection → YOLOv8 weights: loads model (evidence: `pages/3_Video Detection.py`)
- Live detection → YOLOv8 weights: uses model
- Image detection → Report helpers: calls reporting (evidence: `pages/2_Image Detection.py`)
- Video detection → Report helpers: calls reporting (evidence: `pages/3_Video Detection.py`)
- Report helpers → Saved contacts: reads and writes (evidence: `sample_utils/report.py`)
- Report helpers → Browser geolocation: requests location (evidence: `sample_utils/report.py`)
- Report helpers → Nominatim: reverse geocodes (evidence: `sample_utils/report.py`)
- Report helpers → Authority channels: prepares report channels (evidence: `sample_utils/report.py`)
- CRDDC2022 data → Dataset preparation: provides dataset (evidence: `README.md`)
- Dataset preparation → Model training: prepares data for (evidence: `README.md`)
- Model training → Evaluation: model evaluated by (evidence: `README.md`)
