# quantamaster/roadguard architecture

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

- Interactive diagram: https://gitdiagram.com/quantamaster/roadguard
- Repository: https://github.com/quantamaster/roadguard

## Overview

##### Project Type and Purpose
- This is a full-stack AI-driven web & mobile PWA for road distress detection.
- Front-end: TypeScript + React + Vite (files like App.tsx, index.tsx, service-worker.ts, manifest.json).
- Backend (described in README, not in this repo): Python inference service using OpenCV and SAM, plus geo-tag storage.

##### Main Components
1. User Device (Web/Mobile Browser)
– React App (App.tsx, index.html, index.tsx)
– PWA Layer: service-worker.ts, manifest.json, metadata.json
– Static Assets & Config: vite.config.ts, constants.ts, types.ts
2. API Layer / Gateway
– HTTPS endpoints exposed by the Python backend or AI Studio App
– Authentication (e.g., GEMINI_API_KEY in .env.local)
3. Backend Inference Service
– Python ML Server (main.py, requirements.txt)
– Computer Vision (OpenCV)
– AI Models:
- Detection Stage (custom model)
- Segment Anything Model (SAM) for mask segmentation
– Post-Processing: mask overlay generation, geo-coordinate tagging
4. Data Storage
– Temporary in-memory or file store for masks
– Persistent store (e.g., database or GIS dashboard) for geo‐tagged results
5. External Services
– Gemini API or other LLM/AI APIs (if used)
– Mapping service or GIS dashboard integration

##### Architectural Patterns & Design Principles
- Three-Tier Architecture:
– Presentation (React PWA)
– Application/API Layer (REST or WebSocket)
– ML Inference & Data Layer
- PWA Best Practices: offline support (service-worker), manifest for installability
- Componentization: small React components (App.tsx, constants.ts, types.ts)
- Separation of Concerns: UI vs. AI logic vs. data persistence

##### Essential Details to Capture
- The React entrypoint (index.html → index.tsx → App.tsx)
- PWA capabilities (service-worker.ts, manifest.json)
- Vite build & configuration (vite.config.ts)
- ML pipeline stages (Detection → SAM → Post-Processing)
- Geo-tag and visualization feedback loop to front-end

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend – React PWA"
        direction TB
        IDX["index.html"]:::frontend
        ITX["index.tsx"]:::frontend
        APP["App.tsx"]:::frontend
        SW["service-worker.ts"]:::frontend
        MAN["manifest.json"]:::frontend
        META["metadata.json"]:::frontend
        VITE["vite.config.ts"]:::frontend
        TSCONF["tsconfig.json"]:::frontend
        CONST["constants.ts"]:::frontend
        TYPES["types.ts"]:::frontend
        PKG["package.json"]:::frontend
        PKGLK["package-lock.json"]:::frontend
        README["README.md"]:::docs
        INSIGHT["roadguard-insights.html"]:::docs
    end

    %% API Layer
    subgraph "API Gateway" 
        direction TB
        API["REST API / WebSocket"]:::api
        AUTH["Auth (GEMINI_API_KEY)"]:::api
    end

    %% Backend Inference Service
    subgraph "Backend – Inference Service"
        direction TB
        ML_SRV["Python ML Server (main.py)"]:::ml
        DET["Detection Stage (Custom Model)"]:::ml
        SAM["Segmentation Stage (SAM Model)"]:::ml
        POST["Post-Processing & Geo-Tagging"]:::ml
    end

    %% Data & External
    subgraph "Data & External Services"
        direction TB
        STORE["Persistent Data Store"]:::data
        TMP["Temp Mask Store"]:::data
        LLM["LLM / Gemini API"]:::external
        MAPAPI["Mapping / GIS Service"]:::external
    end

    %% User Device
    USER["User Device (Browser / Mobile)"]:::user

    %% Connections
    USER -->|"loads PWA"| IDX
    IDX -->|"bootstraps"| ITX
    ITX -->|"renders"| APP
    APP -->|"registers SW"| SW
    APP -->|"fetch config"| VITE
    APP -->|"uses constants/types"| CONST
    APP -->|"user upload POST /analyze"| API
    API -->|"auth verified"| AUTH
    API -->|"invoke inference"| ML_SRV
    ML_SRV -->|"run detection"| DET
    DET -->|"mask proposals"| SAM
    SAM -->|"segmented masks"| POST
    POST -->|"store masks"| TMP
    POST -->|"geo-tagged data"| STORE
    POST -->|"notify front-end"| API
    ML_SRV -->|"optional LLM call"| LLM
    ML_SRV -->|"map integration"| MAPAPI
    STORE -->|"serve results"| API
    API -->|"WebSocket update"| APP

    %% Click Events
    click IDX "https://github.com/quantamaster/roadguard/blob/main/index.html"
    click ITX "https://github.com/quantamaster/roadguard/blob/main/index.tsx"
    click APP "https://github.com/quantamaster/roadguard/blob/main/App.tsx"
    click SW "https://github.com/quantamaster/roadguard/blob/main/service-worker.ts"
    click MAN "https://github.com/quantamaster/roadguard/blob/main/manifest.json"
    click META "https://github.com/quantamaster/roadguard/blob/main/metadata.json"
    click VITE "https://github.com/quantamaster/roadguard/blob/main/vite.config.ts"
    click TSCONF "https://github.com/quantamaster/roadguard/blob/main/tsconfig.json"
    click CONST "https://github.com/quantamaster/roadguard/blob/main/constants.ts"
    click TYPES "https://github.com/quantamaster/roadguard/blob/main/types.ts"
    click PKG "https://github.com/quantamaster/roadguard/blob/main/package.json"
    click PKGLK "https://github.com/quantamaster/roadguard/blob/main/package-lock.json"
    click README "https://github.com/quantamaster/roadguard/blob/main/README.md"
    click INSIGHT "https://github.com/quantamaster/roadguard/blob/main/roadguard-insights.html"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef api fill:#D0FFD6,stroke:#228B22,color:#000
    classDef ml fill:#FFE0B2,stroke:#FF8C00,color:#000
    classDef data fill:#E0E0E0,stroke:#666,color:#000
    classDef external fill:#E0E0E0,stroke:#666,color:#000
    classDef user fill:#FFFFFF,stroke:#000,color:#000
    classDef docs fill:#F0F0F0,stroke:#999,color:#000
```
