# queryplanner/onnx-web-runtime-inference-for-pothole-detection architecture

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

- Interactive diagram: https://gitdiagram.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection
- Repository: https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection

## Overview

##### Project Type and Purpose
- This is a full‐stack web application for pothole detection and reporting.
- Frontend: React + TypeScript (Vite) that uploads images, runs ONNX model inference in‐browser, extracts GPS from EXIF, and displays an interactive map.
- Backend: FastAPI (Python) exposing two HTTP endpoints (/api/report, /api/map), persisting reports to NeonDB (PostgreSQL serverless), and generating Folium‐based heat maps.

##### File Structure
- Top‐level files:
- App.tsx, index.tsx, index.html – entry points for the SPA
- vite.config.ts – dev server and proxy config pointing `/api` to FastAPI
- services/potholeDetector.ts – ONNX runtime inference wrapper
- components/… – UI pieces (Header, Loader, Stats)
- types.ts, metadata.json – shared type definitions and metadata
- backend/:
- main.py – FastAPI application with two endpoints
- requirements.txt – Python dependencies (fastapi, asyncpg, folium, etc.)
- backend/README.md – backend setup instructions
- Deployment scripts and configs are present for frontend (build in Vercel/Netlify) and backend (Railway/Render).

##### README for Additional Insights
- Confirms the two‐component architecture (React frontend, FastAPI backend).
- Describes API contracts, database schema, feature flow (upload → detect → report → map).

a. Main Components
- User’s browser (SPA client)
- Frontend modules:
- Image Uploader & EXIF parser
- ONNX Runtime (in‐browser model)
- Reporting Service (POST /api/report)
- Viewer (GET /api/map)
- Backend (FastAPI app)
- Database (NeonDB / PostgreSQL)
- External services: ONNX model file, map tile provider (e.g., OpenStreetMap)
b. Relationships & Data Flows
1. User opens SPA → React renders App.tsx
2. User selects image → services/potholeDetector.ts runs ONNX inference → components/Stats show count
3. If GPS EXIF present, frontend POSTs multipart/form-data to FastAPI /api/report
4. Backend (main.py) validates, uses asyncpg to INSERT into pothole_reports table
5. User clicks “VIEW MAP” → frontend GETs /api/map → backend queries DB, generates Folium HTML, returns to client
6. Frontend displays interactive map with heatmap overlay and markers
c. Architectural Patterns & Design Principles
- Single‐Page Application (SPA) disjoint from REST API
- Service‐layer separation in frontend (components vs. services vs. types)
- Asynchronous non‐blocking I/O in backend (FastAPI + asyncpg)
- Clear separation of concerns: inference, data persistence, and presentation
d. Key Technologies & Frameworks
- Frontend: React, TypeScript, Vite, ONNX Runtime Web
- Backend: FastAPI, Python, asyncpg, Folium
- Database: NeonDB (PostgreSQL serverless)
- Build/Deploy: pnpm/npm, uvicorn, Railway/Render, Vercel/Netlify

##### Detail Without Overthinking
- Every distinct module or layer: UI, services, API, DB, external.
- API endpoints and data formats (multipart/form-data, JSON).
- Model file location and EXIF metadata extraction step.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        User["User Browser"]:::external
        IndexHTML["index.html"]:::frontend
        IndexTSX["index.tsx"]:::frontend
        AppTSX["App.tsx"]:::frontend
        UI_Header["Header"]:::frontend
        UI_Loader["Loader"]:::frontend
        UI_Stats["Stats"]:::frontend
        Service_Detector["potholeDetector.ts"]:::frontend
        Types["types.ts"]:::frontend
        Metadata["metadata.json"]:::frontend
        ViteConfig["vite.config.ts"]:::frontend
        Package["package.json"]:::frontend
        TSConfig["tsconfig.json"]:::frontend
        MapViewer["Map Viewer"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        direction TB
        API_Report["POST /api/report"]:::backend
        API_Map["GET /api/map"]:::backend
        BackendMain["main.py"]:::backend
        BackendReq["requirements.txt"]:::backend
        BackendReadme["README.md"]:::backend
        MapGen["Folium Heatmap Generator"]:::backend
    end

    %% Database
    DB["pothole_reports (NeonDB)"]:::database

    %% External Services
    ONNXModel["ONNX Model File"]:::external
    MapTiles["Map Tile Provider"]:::external

    %% Connections - Frontend Flow
    User --> IndexHTML
    IndexHTML --> IndexTSX
    IndexTSX --> AppTSX
    AppTSX --> UI_Header
    AppTSX --> UI_Loader
    AppTSX --> UI_Stats
    UI_Stats --> Service_Detector
    Service_Detector -->|"infer & parse EXIF"| ONNXModel
    Service_Detector -->|"POST report"| API_Report
    AppTSX --> MapViewer
    MapViewer -->|"GET map"| API_Map

    %% Backend Process
    API_Report --> BackendMain
    BackendMain --> DB
    API_Map --> BackendMain
    BackendMain --> MapGen
    MapGen --> DB

    %% Map Tiles Integration
    MapViewer -->|"tile requests"| MapTiles

    %% Click Events - Frontend
    click IndexHTML "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/index.html"
    click IndexTSX "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/index.tsx"
    click AppTSX "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/App.tsx"
    click UI_Header "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/components/Header.tsx"
    click UI_Loader "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/components/Loader.tsx"
    click UI_Stats "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/components/Stats.tsx"
    click Service_Detector "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/services/potholeDetector.ts"
    click Types "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/types.ts"
    click Metadata "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/metadata.json"
    click ViteConfig "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/vite.config.ts"
    click Package "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/package.json"
    click TSConfig "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/tsconfig.json"

    %% Click Events - Backend
    click BackendMain "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/backend/main.py"
    click BackendReq "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/backend/requirements.txt"
    click BackendReadme "https://github.com/queryplanner/onnx-web-runtime-inference-for-pothole-detection/blob/main/backend/README.md"

    %% Styling
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D0FFD8,stroke:#228B22,color:#228B22
    classDef database fill:#FFE0B2,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F0F0F0,stroke:#696969,color:#696969
```
