# shubhank-saxena/pothole-detection architecture

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

- Interactive diagram: https://gitdiagram.com/shubhank-saxena/pothole-detection
- Repository: https://github.com/shubhank-saxena/pothole-detection

## Overview

##### Project type and purpose
- This is an end-to-end pothole detection system combining:
- A mobile front-end (Apache Cordova Android/iOS app)
- A lightweight ingestion server (Server 1)
- A high-compute server running Mask RCNN (Server 2)
- Google Cloud Storage (GCS) bucket for file sharing
- Google Maps for visualization
- Purpose: collect geo-tagged road images from users, run Mask RCNN to detect potholes, encode results in filenames, and plot them on Google Maps.

##### File structure
- Root: Jupyter notebooks (development & demo), `custom.py` (train/infer CLI), `search_bing_api.py` (data-download helper).
- `test_dataset`, `Download_data`: raw/test data.
- `cloud_files_gcp`: likely scripts to push/pull from GCS.
- No database—state is encoded in file names.
- Cron jobs implied from README for nightly batch processing.

##### Pull architecture notes from README
- Two GCP VMs:
- VM1 (ingestion) gathers/uploads every 24 hr
- VM2 (compute) runs Mask RCNN once per day via cron
- Single GCS bucket shared between VMs
- Mobile app → VM1 via API → GCS → VM2 batch → GCS → Google Maps

##### Main components and their interactions
a. Mobile Application (Apache Cordova)
- Captures photo + GPS → uploads via REST API to Ingestion Server
b. Ingestion Server (Server 1)
- Receives images (filename = latitude‐longitude.jpg)
- Compresses & stores in GCS bucket
c. GCS Bucket
- Shared filesystem for both servers
- Raw images and processed images
d. Compute Server (Server 2)
- Cron‐scheduled job
- Pulls raw images from GCS
- Runs Mask RCNN on each image (via `custom.py`)
- Renames output with pothole count & size and GPS:
`[count]-[size]-[lat]-[lon].jpg`
- Writes results back to GCS
e. Google Maps API
- Reads processed filenames from GCS
f. Training Environment (optional component)
- Local or cloud VM running `custom.py train ...`
- Uses `train/val` dataset inside `customImages`
- Outputs weights (`.h5`) to GCS or logs folder

##### Architectural patterns and design principles
- Microservices style: ingestion vs. compute decoupled via shared storage
- Batch processing for compute‐heavy ML tasks (daily cron)
- No relational DB—metadata encoded in filenames
- Cloud‐native: uses GCS as a datastore, GCP VMs for compute
- RESTful API for mobile→server communication

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    MobileApp["Mobile App<br/>(Apache Cordova)"]:::client
    IngestionServer["Ingestion Server<br/>(VM1)"]:::server
    ComputeServer["Compute Server<br/>(VM2)"]:::server
    GCS["GCS Bucket"]:::storage
    GoogleMaps["Google Maps API"]:::external

    %% Subgraphs
    subgraph "Ingestion Layer"
        CloudScripts["cloud_files_gcp"]:::server
    end

    subgraph "Compute Layer"
        CronJob("Cron Job<br/>Daily @21:00 IST"):::server
        MaskRCNNEngine["custom.py<br/>(Mask RCNN CLI)"]:::server
    end

    subgraph "Offline Training"
        subgraph "Training & Demo Notebooks"
            NB1["Final_file_for_tata_innoverse.ipynb"]:::offline
            NB2["Project_update_24th_05_07pm.ipynb"]:::offline
            NB3["TechFest_Project_2019_PSA.ipynb"]:::offline
        end
        DataHelper["Download_data/search_bing_api.py"]:::offline
        TestData["test_dataset/"]:::offline
        ImagesData["Images/"]:::offline
        subgraph "Reference Pipelines"
            RefNB1["VideoFormationMaskRCNN.ipynb"]:::offline
            RefNB2["successfulVideoFormationWithMaskRCNN.ipynb"]:::offline
            Visualize["visualize.py"]:::offline
        end
    end

    README["README.md"]:::doc

    %% Data Flows
    MobileApp -->|POST image: lat-long.jpg| IngestionServer
    IngestionServer -->|PUT raw images| GCS
    CronJob -->|GET raw/*.jpg| GCS
    CronJob --> MaskRCNNEngine
    MaskRCNNEngine -->|PUT count-size-lat-lon.jpg| GCS
    GCS -->|READ processed metadata| GoogleMaps

    %% Offline Training Flows
    TestData --> NB1
    ImagesData --> NB1
    NB1 -->|uses search_bing_api| DataHelper
    DataHelper -->|prepares data| NB2
    NB2 -->|trains model via custom.py| NB3

    %% Click Events
    click CloudScripts "https://github.com/shubhank-saxena/pothole-detection/tree/master/cloud_files_gcp/"
    click MaskRCNNEngine "https://github.com/shubhank-saxena/pothole-detection/blob/master/custom.py"
    click DataHelper "https://github.com/shubhank-saxena/pothole-detection/blob/master/Download_data/search_bing_api.py"
    click NB1 "https://github.com/shubhank-saxena/pothole-detection/blob/master/Final_file_for_tata_innoverse.ipynb"
    click NB2 "https://github.com/shubhank-saxena/pothole-detection/blob/master/Project_update_24th_05_07pm.ipynb"
    click NB3 "https://github.com/shubhank-saxena/pothole-detection/blob/master/TechFest_Project_2019_PSA.ipynb"
    click TestData "https://github.com/shubhank-saxena/pothole-detection/tree/master/test_dataset/"
    click ImagesData "https://github.com/shubhank-saxena/pothole-detection/tree/master/Images/"
    click RefNB1 "https://github.com/shubhank-saxena/pothole-detection/blob/master/old_ref_files/VideoFormationMaskRCNN.ipynb"
    click RefNB2 "https://github.com/shubhank-saxena/pothole-detection/blob/master/old_ref_files/successfulVideoFormationWithMaskRCNN.ipynb"
    click Visualize "https://github.com/shubhank-saxena/pothole-detection/blob/master/old_ref_files/visualize.py"
    click README "https://github.com/shubhank-saxena/pothole-detection/blob/master/README.md"

    %% Styles
    classDef client fill:#FFEB3B,stroke:#333,stroke-width:1px
    classDef server fill:#2196F3,stroke:#333,stroke-width:1px
    classDef storage fill:#4CAF50,stroke:#333,stroke-width:1px
    classDef external fill:#9C27B0,stroke:#333,stroke-width:1px
    classDef offline fill:#FF9800,stroke:#333,stroke-width:1px
    classDef doc fill:#795548,stroke:#333,stroke-width:1px
```
