Interactive pothole mapping & monitoring dashboard with real-time AI inference
This repository is part of a two-component system for pothole tracking and classification:
| Repository | Description |
|---|---|
| ML-PotholeClassification-IAI | 🧠 ML Pipeline — Model training, dataset preparation, and ONNX export |
| PotholeTrackApp-MLClassifier | 🗺️ This repo — Web application with interactive map, pothole visualization, and real-time inference |
PotholeTrack is a Progressive Web Application (PWA) that provides municipalities and infrastructure teams with an intelligent road monitoring system. The application processes uploaded road imagery through a two-stage ML pipeline:
- Detection Stage: YOLOv9-seg instance segmentation identifies and localizes potholes
- Severity Stage: YOLO11n classifier categorizes each detection into Low/Medium/High severity bands aligned with ASTM D6433 standards
The trained models are deployed via ONNX Runtime for efficient CPU inference, enabling real-time processing without GPU requirements.
- AI-Powered Detection: Two-stage YOLOv9-seg + YOLO11n pipeline for detection and severity classification
- Interactive Mapping: Google Maps integration with color-coded severity markers (🔴 High, 🟠 Medium, 🟢 Low)
- GPS Auto-Extraction: Automatically reads coordinates from image EXIF metadata
- Status Tracking: Mark potholes as active or fixed with real-time dashboard updates
- CSV Export: Download filtered or complete datasets for reporting and analysis
- Mobile-Optimized PWA: Install on devices for offline-capable access with responsive design
- Re-Analysis: Rerun detection on uploaded images as models improve
| Metric | Value |
|---|---|
| Precision | 0.80 |
| Recall | 0.70 |
| mAP@50 | 0.76 |
| mAP@50-95 | 0.37 |
| Training | 52 epochs |
| Metric | Value |
|---|---|
| Top-1 Accuracy | 0.76 |
| Classes | Low, Medium, High |
| Training | 28 epochs |
For model training details and methodology, see the ML-PotholeClassification-IAI repository.
┌─────────────────────────────────────────────────────────────────────┐
│ React Frontend (PWA) │
│ Google Maps • Filter Panel • Stats Dashboard │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Express.js Backend │
│ Drizzle ORM • Image Storage • REST API │
└─────────────────────────────────────────────────────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────────────┐
│ PostgreSQL (Neon) │ │ Python FastAPI Service │
│ Images • Detections │ │ YOLOv9-seg + YOLO11n-cls ONNX │
└───────────────────────────┘ └───────────────────────────────────┘
Frontend:
- React 18 + TypeScript + Vite
- TanStack Query (server state)
- Tailwind CSS + shadcn/ui
- Google Maps JavaScript API
Backend:
- Node.js + Express
- Drizzle ORM + Neon PostgreSQL
- TypeScript with ES modules
AI/ML Service:
- Python FastAPI + Uvicorn
- ONNX Runtime for inference
- Ultralytics model format
- Node.js 18+
- Python 3.10+
- PostgreSQL database
- Google Maps API Key (Get one here)
# Clone the repository
git clone https://github.com/RedLynx101/PotholeTrackApp-MLClassifier.git
cd PotholeTrackApp-MLClassifier
# Install Node.js dependencies
npm install
# Install Python dependencies
pip install -r python_service/requirements.txt
# Configure environment variables
cp env.example .env
# Edit .env with your API keys and database URL# Start both services (Node.js + Python)
npm run devThis starts:
- Express server (frontend + API) on port 5000
- Python YOLO service on port 8000
Run the entire stack with Docker Compose:
# Configure environment
cp env.example .env
# Edit .env with your credentials
# Build and start
docker compose up --build -d
# View logs
docker compose logs -f web
docker compose logs -f ml
# Stop services
docker compose down| Container | Description | Port |
|---|---|---|
web |
Express/Vite frontend + API | 5000 |
ml |
Python ONNX inference service | 8000 |
| Variable | Description | Required |
|---|---|---|
VITE_GOOGLE_MAPS_API_KEY |
Google Maps JavaScript API key | ✅ |
DATABASE_URL |
PostgreSQL connection string | ✅ |
SESSION_SECRET |
Express session secret | ✅ |
PYTHON_SERVICE_URL |
Override ML service URL | ❌ |
├── client/ # React frontend (PWA)
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── pages/ # Route pages
│ │ └── lib/ # Utilities
│ └── index.html
├── server/ # Express.js backend
│ ├── routes.ts # API endpoints
│ ├── storage.ts # Database layer
│ └── objectStorage.ts # Image storage
├── python_service/ # AI inference service
│ ├── main.py # FastAPI server
│ ├── detector/ # YOLOv9-seg ONNX model
│ └── severity/ # YOLO11n-cls ONNX model
├── shared/ # Shared TypeScript types
│ └── schema.ts # Database schema (Drizzle)
└── public/ # Static assets + PWA manifest
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/potholes |
Retrieve all images with detections |
POST |
/api/potholes/upload |
Upload image and run detection |
PATCH |
/api/potholes/:id |
Update image metadata |
PATCH |
/api/potholes/:id/location |
Set GPS coordinates |
POST |
/api/potholes/:id/reanalyze |
Rerun detection pipeline |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/potholes/stats |
Get detection statistics |
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Health check |
POST |
/predict |
Run AI detection pipeline |
Based on ASTM D6433 pavement distress standards:
| Severity | Marker | Description |
|---|---|---|
| High | 🔴 Red | Severe hazard, exposed base layers, immediate attention required |
| Medium | 🟠 Orange | Moderate damage, visible edge raveling |
| Low | 🟢 Green | Minor surface distress, minimal traffic impact |
| Fixed | ⚪ Gray | Repaired, marked inactive |
Map not loading:
- Verify
VITE_GOOGLE_MAPS_API_KEYis set correctly - Ensure Maps JavaScript API is enabled in Google Cloud Console
Python service not starting:
- Check ONNX models exist in
python_service/detector/andpython_service/severity/ - Verify Python dependencies:
pip install -r python_service/requirements.txt
Database errors:
- Confirm
DATABASE_URLis correct and PostgreSQL is accessible - Run
npm run db:pushto sync schema
This project was developed as part of CMU 95-891: Introduction to Artificial Intelligence (Fall 2025).
Evelynn Chen
Noah Hicks
Yiying Lu
Iteoluwa Ibitoye
This project is licensed under the MIT License - see the LICENSE file for details.
- Ultralytics for the YOLO framework
- Google Maps Platform for mapping services
- shadcn/ui for React components
- MWPD and PothRGBD dataset creators for training data
- ASTM International for the D6433 pavement distress standards
Built with ❤️ at Carnegie Mellon University