# nirbhayph/spothole architecture

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

- Interactive diagram: https://gitdiagram.com/nirbhayph/spothole
- Repository: https://github.com/nirbhayph/spothole

## Overview

##### Project type and purpose
- This is a full-stack, user-facing Single Page Application (SPA) built with React.js.
- Purpose: Citizen-side web/mobile front end for “Spothole,” an AI-powered pothole detection, reporting, routing and management solution.
- It consumes REST APIs from a Flask + deep-learning backend (pothole.validation, geocoding, report management) and integrates external services like Google Maps and Google OAuth.

##### File structure
- Top level:
- public/ & build/ – static assets, HTML templates, generated React build
- src/ – React source code
- package.json, package-lock.json – dependency manifests
- src/ subdivisions:
- components/ – reusable UI pieces (alerts, camera, forms, map markers, steppers)
- navigation/ – routing and layout (navbar, dashboard, profile, route screens)
- utility/ – constants (API endpoints, maps keys)
- serviceWorker.js – PWA support
- The existence of build/, public/ and react-scripts indicates a create-react-app based SPA deployed statically via GitHub Pages.

##### README for additional insights
- 5 major feature modules: Report, My Complaints, Route Navigation, Profile, Sign In.
- External dependencies: React Google Maps, Axios, FilePond, Google OAuth, Material-UI, CNN backend for media validation, Unsplash for backgrounds.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Browser / Mobile WebView"
        direction TB
        User["User"]:::frontend
        ReactSPA["React SPA"]:::frontend
        ServiceWorker["Service Worker & Cache"]:::frontend
    end

    %% UI Modules
    subgraph "SPA Feature Modules"
        direction TB
        SignIn["Sign In"]:::frontend
        SignUp["User Registration"]:::frontend
        ReportFeature["Report Feature (New Report)"]:::frontend
        MyComplaints["My Complaints Dashboard"]:::frontend
        RouteNav["Route Navigation Feature"]:::frontend
        Profile["Profile Management"]:::frontend
        SearchPlaces["Search & Geocoding"]:::frontend
        CameraUpload["Camera Capture & Upload"]:::frontend
        MediaValidationUI["Media Validation Feedback"]:::frontend
        CommentsDetail["Comments & Complaints Details"]:::frontend
        Error404["Error Handling (404)"]:::frontend
    end

    %% REST Client
    AxiosClient["REST API Client (Axios)"]:::frontend
    Constants["Utility Constants"]:::frontend

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleMaps["Google Maps JS API"]:::external
        GoogleOAuth["Google OAuth2.0"]:::external
        Unsplash["Unsplash API"]:::external
    end

    %% Backend Layer
    subgraph "Backend API Gateway (Flask)"
        direction TB
        AuthService["Authentication / Session Service"]:::backend
        MediaValidation["Media Validation Microservice (CNN)"]:::backend
        GeocodeService["Geocoding Service"]:::backend
        ReportService["Report Management Service"]:::backend
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        Database["Database (Reports, Users, Comments)"]:::datastore
        FileStorage["File Storage (Uploads)"]:::datastore
    end

    %% Connections
    User -->|uses| ReactSPA
    ReactSPA -->|registers with| AuthService
    ReactSPA -->|auth via| GoogleOAuth
    ReactSPA -->|calls| AxiosClient
    ReactSPA -->|uses| ServiceWorker
    ReactSPA -->|loads config| Constants

    AxiosClient -->|POST image| MediaValidation
    MediaValidation -->|validation result| ReactSPA
    AxiosClient -->|POST report data| ReportService
    AxiosClient -->|GET complaints| ReportService
    AxiosClient -->|GET geocoded data| GeocodeService
    ReactSPA -->|loads maps & geocode| GoogleMaps
    ReactSPA -->|loads OAuth UI| GoogleOAuth
    ReactSPA -->|loads backgrounds| Unsplash

    ReportService -->|store| Database
    AuthService -->|validate| Database
    CommentsDetail -->|fetch/update| ReportService
    MediaValidation -->|fetch model| FileStorage

    ServiceWorker -->|cache assets| ReactSPA
    ServiceWorker -->|offline fallback| Error404

    %% Arrow styling
    classDef frontend fill:#cfe2f3,stroke:#6fa8dc,color:#000
    classDef backend fill:#d9ead3,stroke:#93c47d,color:#000
    classDef external fill:#f4cccc,stroke:#ea9999,color:#000
    classDef datastore fill:#ffd966,stroke:#f1c232,color:#000

    %% Click Events
    click ReactSPA "https://github.com/nirbhayph/spothole/blob/develop/src/App.js"
    click ReactSPA "https://github.com/nirbhayph/spothole/blob/develop/src/index.js"
    click ServiceWorker "https://github.com/nirbhayph/spothole/blob/develop/src/serviceWorker.js"
    click ServiceWorker "https://github.com/nirbhayph/spothole/blob/develop/build/service-worker.js"
    click ServiceWorker "https://github.com/nirbhayph/spothole/blob/develop/public/manifest.json"
    click AxiosClient "https://github.com/nirbhayph/spothole/blob/develop/src/components/service/index.js"
    click GoogleOAuth "https://github.com/nirbhayph/spothole/blob/develop/src/components/authentication/index.js"
    click SignUp "https://github.com/nirbhayph/spothole/blob/develop/src/components/signup/index.js"
    click ReportFeature "https://github.com/nirbhayph/spothole/blob/develop/src/components/new_report/index.js"
    click MyComplaints "https://github.com/nirbhayph/spothole/blob/develop/src/navigation/dashboard/index.js"
    click RouteNav "https://github.com/nirbhayph/spothole/blob/develop/src/navigation/routing/index.js"
    click RouteNav "https://github.com/nirbhayph/spothole/blob/develop/src/components/route_maker/index.js"
    click Profile "https://github.com/nirbhayph/spothole/blob/develop/src/navigation/profile/index.js"
    click SearchPlaces "https://github.com/nirbhayph/spothole/blob/develop/src/components/search_places/index.js"
    click CameraUpload "https://github.com/nirbhayph/spothole/blob/develop/src/components/camera/index.js"
    click CameraUpload "https://github.com/nirbhayph/spothole/blob/develop/src/components/uploads/index.js"
    click MediaValidationUI "https://github.com/nirbhayph/spothole/blob/develop/src/components/severity_indicator/index.js"
    click MediaValidationUI "https://github.com/nirbhayph/spothole/blob/develop/src/components/linear_progress/index.js"
    click CommentsDetail "https://github.com/nirbhayph/spothole/blob/develop/src/components/comments/index.js"
    click CommentsDetail "https://github.com/nirbhayph/spothole/blob/develop/src/components/detailed_data_modal/index.js"
    click Error404 "https://github.com/nirbhayph/spothole/blob/develop/src/components/not_found/index.js"
    click Error404 "https://github.com/nirbhayph/spothole/blob/develop/build/404/index.html"
    click Constants "https://github.com/nirbhayph/spothole/blob/develop/src/utility/constants.js"
```
