How queryplanner/onnx-web-runtime-inference-for-pothole-detection works
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.