How ghanenxra/roadpulse-ai works
RoadPulse AI is a municipal road-health dashboard whose core workflow turns bus-camera footage or submitted detections into mapped, scored road defects, then tracks repair accountability and verification. The frontend provides map, road, processing, authority, and reporting views through a FastAPI service backed by relational road, detection, metric, and issue records. README capabilities include spatial deduplication, road snapping, SLA tracking, and PDF/CSV exports; those subsystems are represented at supported enclosing paths where implementation details were not sampled. Backend router wiring and selected service behavior are evidenced; several feature-level links follow documented capabilities.
Main entry points: main.py FastAPI application · database.py Road health records · api.ts API client · ingest.py Detection ingestion
Components 26
Dashboard
- Dashboard views
frontend/app - Road health map
frontend/app/map/page.tsx - Road details
frontend/app/roads - Processing center
frontend/app/processing/page.tsx - Authority tracker
frontend/app/authority/page.tsx - Reports view
frontend/app/reports/page.tsx - Interactive map
frontend/components/MapComponent.tsx - Week selection
frontend/context/WeekContext.tsx - API client
frontend/lib/api.ts
Capture and Analysis
- Video processing
backend/api/processing.py - Defect inference
backend/services/detection_service.py - Detection ingestion
backend/api/ingest.py - Spatial deduplication
backend/services/aggregation_service.py - Risk scoring
backend/services/scoring_service.py - Road snapping
backend/data
Repair Accountability
- Issue and SLA tracking
backend/api/authority.py - Repair verification
backend/services/verification_service.py - PDF and CSV exports
backend/services/report_service.py - Reports API
backend/api/reports.py
API and State
- Road data API
backend/api/roads.py - Metrics API
backend/api/metrics.py - FastAPI application
backend/main.py - Road health records
backend/models/database.py
Other components
- Municipal user
- OSRM service
- Municipal authorities
Connections 32
- Municipal user → Dashboard views: uses
- Municipal user → Processing center: submits footage
- Municipal user → Authority tracker: updates status
- Dashboard views → API client: requests data
- Road health map → Interactive map: renders map
- Road details → API client: requests roads
- Processing center → API client: starts jobs
- Authority tracker → API client: manages issues
- Reports view → API client: requests exports
- Week selection → Dashboard views: selects week
- API client → FastAPI application: calls API
- FastAPI application → Video processing: dispatches
- FastAPI application → Detection ingestion: dispatches
- FastAPI application → Road data API: dispatches
- FastAPI application → Metrics API: dispatches
- FastAPI application → Authority tracker: serves requests
- FastAPI application → Reports API: dispatches
- Video processing → Defect inference: runs inference
- Defect inference → Detection ingestion: submits detections
- Detection ingestion → Road health records: writes detections
- Detection ingestion → Road health records: updates live metrics
- Detection ingestion → Risk scoring: calculates risk
- Spatial deduplication → Road health records: stores clusters
- Road snapping → OSRM service: snaps coordinates
- Road data API → Road health records: reads road records
- Metrics API → Road health records: reads metrics
- Issue and SLA tracking → Road health records: updates issue records
- Issue and SLA tracking → Repair verification: triggers verification
- Repair verification → Road health records: records outcome
- Municipal authorities → Issue and SLA tracking: receives tickets
- Reports API → PDF and CSV exports: generates exports
- PDF and CSV exports → Road health records: reads audit data