# shrestha-sachin/pothole-verification architecture

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

- Interactive diagram: https://gitdiagram.com/shrestha-sachin/pothole-verification
- Repository: https://github.com/shrestha-sachin/pothole-verification

## Overview

Pothole Verification is a Streamlit system for finding pothole candidates in road video, grouping detections into events, applying verification policies, and supporting human review and export. Its broader workflow also includes image annotation and dataset preparation for detector and verifier training. The dashboard excerpt is partial, so documented workflow edges are included where the README establishes them; implementation detail beyond the shown source references is left out.

Main entry points: [`dashboard/app.py`](https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/app.py) (Review Dashboard), [`dashboard/annotate.py`](https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/annotate.py) (Annotation Dashboard), [`data/annotations`](https://github.com/shrestha-sachin/pothole-verification/tree/main/data/annotations) (Annotation Files), [`scripts/generate_crops.py`](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/generate_crops.py) (Verifier Crop Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Video Review"]
  node_dashboard["Review Dashboard<br/>[app.py]"]
  node_database[("Review Database<br/>[database.py]")]
  node_report["CSV Report"]
end

subgraph group_analysis["Detection Analysis"]
  node_sampler["Frame Sampler<br/>[video_sampler.py]"]
  node_detector["YOLO Detector<br/>[inference.py]"]
  node_grouper["Event Grouper<br/>[event_grouper.py]"]
  node_policies["A/B/C Policies<br/>[policies.py]"]
  node_verifier["Visual Verifier<br/>[interface.py]"]
  node_crop_processing["Crop Processing<br/>[preprocessing.py]"]
  node_event_evaluation["Ground Truth Matching<br/>[matcher.py]"]
  node_renderer["Video Renderer"]
end

subgraph group_annotation["Image Annotation"]
  node_annotator["Annotation Dashboard<br/>[annotate.py]"]
  node_canvas["Annotation Canvas<br/>[editor.js]"]
  node_annotation_editor["Editor Logic"]
  node_annotation_helpers["Annotation Storage<br/>[annotations.py]"]
  node_annotation_files["Annotation Files"]
end

subgraph group_datasets["Dataset Preparation"]
  node_inventory["Image Inventory<br/>[build_inventory.py]"]
  node_yolo_export["YOLO Label Export<br/>[export_yolo.py]"]
  node_crop_generation["Verifier Crop Generation<br/>[generate_crops.py]"]
  node_detector_training["Detector Training<br/>[train_detector.py]"]
  node_verifier_training["Verifier Training<br/>[train.py]"]
end

node_user(("Reviewer"))
node_video["Road Video"]
node_mapillary["Mapillary Images"]
node_video_frames["Extracted Frames<br/>[extract_frames.py]"]

node_user -->|"analyzes video"| node_dashboard
node_video -->|"provides input"| node_dashboard
node_dashboard -->|"samples frames"| node_sampler
node_sampler -->|"feeds frames"| node_detector
node_dashboard -->|"groups detections"| node_grouper
node_dashboard -->|"applies policies"| node_policies
node_dashboard -->|"requests verification"| node_verifier
node_verifier -->|"preprocesses crops"| node_crop_processing
node_dashboard -->|"uses matching"| node_event_evaluation
node_dashboard -->|"renders video"| node_renderer
node_dashboard -->|"persists events"| node_database
node_dashboard -->|"exports report"| node_report
node_user -->|"labels images"| node_annotator
node_annotator -->|"draws boxes"| node_canvas
node_annotator -->|"uses editor"| node_annotation_editor
node_annotator -->|"loads and saves"| node_annotation_helpers
node_annotation_helpers -->|"reads and writes"| node_annotation_files
node_mapillary -->|"browses images"| node_annotator
node_mapillary -->|"indexes images"| node_inventory
node_video -->|"extracts frames"| node_video_frames
node_inventory -.->|"supports labeling"| node_yolo_export
node_annotation_files -->|"exports labels"| node_yolo_export
node_annotation_files -->|"generates crops"| node_crop_generation
node_crop_generation -->|"uses preprocessing"| node_crop_processing
node_yolo_export -.->|"prepares labels"| node_detector_training
node_crop_generation -->|"prepares samples"| node_verifier_training
node_verifier_training -.->|"produces checkpoint"| node_verifier

click node_dashboard "https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/app.py"
click node_sampler "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/detector/video_sampler.py"
click node_detector "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/detector/inference.py"
click node_grouper "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/tracking/event_grouper.py"
click node_policies "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/evaluation/policies.py"
click node_verifier "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/interface.py"
click node_crop_processing "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/preprocessing.py"
click node_event_evaluation "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/evaluation/matcher.py"
click node_renderer "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/video/annotated_renderer.py"
click node_database "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/database.py"
click node_annotator "https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/annotate.py"
click node_canvas "https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/annotation_canvas/editor.js"
click node_annotation_editor "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/annotation_editor.py"
click node_annotation_helpers "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/annotations.py"
click node_annotation_files "https://github.com/shrestha-sachin/pothole-verification/tree/main/data/annotations"
click node_inventory "https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/build_inventory.py"
click node_yolo_export "https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/export_yolo.py"
click node_crop_generation "https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/generate_crops.py"
click node_detector_training "https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/train_detector.py"
click node_verifier_training "https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/train.py"
click node_mapillary "https://github.com/shrestha-sachin/pothole-verification/tree/main/data/raw/mapillary"
click node_video_frames "https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/extract_frames.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_dashboard,node_database,node_report,node_user toneBlue
class node_sampler,node_detector,node_grouper,node_policies,node_verifier,node_crop_processing,node_event_evaluation,node_renderer toneAmber
class node_annotator,node_canvas,node_annotation_editor,node_annotation_helpers,node_annotation_files,node_mapillary toneMint
class node_inventory,node_yolo_export,node_crop_generation,node_detector_training,node_verifier_training toneRose
class node_video toneIndigo
class node_video_frames toneTeal
```

## Components

### Video Review

- [Review Dashboard](https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/app.py): `dashboard/app.py`
- [Review Database](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/database.py): `src/database.py`
- **CSV Report**

### Detection Analysis

- [Frame Sampler](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/detector/video_sampler.py): `src/detector/video_sampler.py`
- [YOLO Detector](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/detector/inference.py): `src/detector/inference.py`
- [Event Grouper](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/tracking/event_grouper.py): `src/tracking/event_grouper.py`
- [A/B/C Policies](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/evaluation/policies.py): `src/evaluation/policies.py`
- [Visual Verifier](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/interface.py): `src/verifier/interface.py`
- [Crop Processing](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/preprocessing.py): `src/verifier/preprocessing.py`
- [Ground Truth Matching](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/evaluation/matcher.py): `src/evaluation/matcher.py`
- [Video Renderer](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/video/annotated_renderer.py): `src/video/annotated_renderer.py`

### Image Annotation

- [Annotation Dashboard](https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/annotate.py): `dashboard/annotate.py`
- [Annotation Canvas](https://github.com/shrestha-sachin/pothole-verification/blob/main/dashboard/annotation_canvas/editor.js): `dashboard/annotation_canvas/editor.js`
- [Editor Logic](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/annotation_editor.py): `src/annotation_editor.py`
- [Annotation Storage](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/annotations.py): `src/annotations.py`
- [Annotation Files](https://github.com/shrestha-sachin/pothole-verification/tree/main/data/annotations): `data/annotations`

### Dataset Preparation

- [Image Inventory](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/build_inventory.py): `scripts/build_inventory.py`
- [YOLO Label Export](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/export_yolo.py): `scripts/export_yolo.py`
- [Verifier Crop Generation](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/generate_crops.py): `scripts/generate_crops.py`
- [Detector Training](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/train_detector.py): `scripts/train_detector.py`
- [Verifier Training](https://github.com/shrestha-sachin/pothole-verification/blob/main/src/verifier/train.py): `src/verifier/train.py`

### Other components

- **Reviewer**
- **Road Video**
- [Mapillary Images](https://github.com/shrestha-sachin/pothole-verification/tree/main/data/raw/mapillary): `data/raw/mapillary`
- [Extracted Frames](https://github.com/shrestha-sachin/pothole-verification/blob/main/scripts/extract_frames.py): `scripts/extract_frames.py`

## Connections

- Reviewer → Review Dashboard: analyzes video (evidence: `README.md`)
- Road Video → Review Dashboard: provides input (evidence: `README.md`)
- Review Dashboard → Frame Sampler: samples frames (evidence: `README.md`)
- Frame Sampler → YOLO Detector: feeds frames (evidence: `README.md`)
- Review Dashboard → Event Grouper: groups detections (evidence: `README.md`)
- Review Dashboard → A/B/C Policies: applies policies (evidence: `README.md`)
- Review Dashboard → Visual Verifier: requests verification (evidence: `dashboard/app.py`)
- Visual Verifier → Crop Processing: preprocesses crops (evidence: `src/verifier/interface.py`)
- Review Dashboard → Ground Truth Matching: uses matching (evidence: `dashboard/app.py`)
- Review Dashboard → Video Renderer: renders video (evidence: `dashboard/app.py`)
- Review Dashboard → Review Database: persists events (evidence: `dashboard/app.py`)
- Review Dashboard → CSV Report: exports report (evidence: `README.md`)
- Reviewer → Annotation Dashboard: labels images (evidence: `README.md`)
- Annotation Dashboard → Annotation Canvas: draws boxes (evidence: `README.md`)
- Annotation Dashboard → Editor Logic: uses editor (evidence: `dashboard/annotate.py`)
- Annotation Dashboard → Annotation Storage: loads and saves (evidence: `dashboard/annotate.py`)
- Annotation Storage → Annotation Files: reads and writes (evidence: `src/annotations.py`)
- Mapillary Images → Annotation Dashboard: browses images (evidence: `README.md`)
- Mapillary Images → Image Inventory: indexes images (evidence: `README.md`)
- Road Video → Extracted Frames: extracts frames (evidence: `README.md`)
- Image Inventory → YOLO Label Export: supports labeling
- Annotation Files → YOLO Label Export: exports labels (evidence: `README.md`)
- Annotation Files → Verifier Crop Generation: generates crops (evidence: `README.md`)
- Verifier Crop Generation → Crop Processing: uses preprocessing (evidence: `scripts/generate_crops.py`)
- YOLO Label Export → Detector Training: prepares labels
- Verifier Crop Generation → Verifier Training: prepares samples (evidence: `README.md`)
- Verifier Training → Visual Verifier: produces checkpoint