# ghanenxra/roadpulse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ghanenxra/roadpulse-ai
- Repository: https://github.com/ghanenxra/roadpulse-ai

## Overview

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: [`backend/main.py`](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/main.py) (FastAPI application), [`backend/models/database.py`](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/models/database.py) (Road health records), [`frontend/lib/api.ts`](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/lib/api.ts) (API client), [`backend/api/ingest.py`](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/ingest.py) (Detection ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard views"]
  node_map_ui["Road health map<br/>[page.tsx]"]
  node_road_ui["Road details"]
  node_processing_ui["Processing center<br/>[page.tsx]"]
  node_authority_ui["Authority tracker<br/>[page.tsx]"]
  node_reports_ui["Reports view<br/>[page.tsx]"]
  node_map_component["Interactive map<br/>[MapComponent.tsx]"]
  node_week_state["Week selection<br/>[WeekContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_ingest["Capture and Analysis"]
  node_video_processing["Video processing<br/>[processing.py]"]
  node_detection["Defect inference"]
  node_ingest_api["Detection ingestion<br/>[ingest.py]"]
  node_clustering["Spatial deduplication"]
  node_scoring["Risk scoring<br/>[scoring_service.py]"]
  node_road_geometry["Road snapping"]
end

subgraph group_accountability["Repair Accountability"]
  node_sla["Issue and SLA tracking<br/>[authority.py]"]
  node_verification["Repair verification"]
  node_reports["PDF and CSV exports<br/>[report_service.py]"]
  node_reports_api["Reports API<br/>[reports.py]"]
end

subgraph group_platform["API and State"]
  node_roads_api["Road data API<br/>[roads.py]"]
  node_metrics_api["Metrics API<br/>[metrics.py]"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_database[("Road health records<br/>[database.py]")]
end

node_municipal_user(("Municipal user"))
node_osrm["OSRM service"]
node_authorities(("Municipal authorities"))

node_municipal_user -->|"uses"| node_dashboard
node_municipal_user -->|"submits footage"| node_processing_ui
node_municipal_user -->|"updates status"| node_authority_ui
node_dashboard -->|"requests data"| node_api_client
node_map_ui -->|"renders map"| node_map_component
node_road_ui -->|"requests roads"| node_api_client
node_processing_ui -->|"starts jobs"| node_api_client
node_authority_ui -->|"manages issues"| node_api_client
node_reports_ui -->|"requests exports"| node_api_client
node_week_state -->|"selects week"| node_dashboard
node_api_client -->|"calls API"| node_backend_app
node_backend_app -->|"dispatches"| node_video_processing
node_backend_app -->|"dispatches"| node_ingest_api
node_backend_app -->|"dispatches"| node_roads_api
node_backend_app -->|"dispatches"| node_metrics_api
node_backend_app -->|"serves requests"| node_authority_ui
node_backend_app -->|"dispatches"| node_reports_api
node_video_processing -->|"runs inference"| node_detection
node_detection -->|"submits detections"| node_ingest_api
node_ingest_api -->|"writes detections"| node_database
node_ingest_api -->|"updates live metrics"| node_database
node_ingest_api -->|"calculates risk"| node_scoring
node_clustering -->|"stores clusters"| node_database
node_road_geometry -.->|"snaps coordinates"| node_osrm
node_roads_api -->|"reads road records"| node_database
node_metrics_api -->|"reads metrics"| node_database
node_sla -->|"updates issue records"| node_database
node_sla -->|"triggers verification"| node_verification
node_verification -->|"records outcome"| node_database
node_authorities -->|"receives tickets"| node_sla
node_reports_api -->|"generates exports"| node_reports
node_reports -->|"reads audit data"| node_database

click node_dashboard "https://github.com/ghanenxra/roadpulse-ai/tree/main/frontend/app"
click node_map_ui "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/map/page.tsx"
click node_road_ui "https://github.com/ghanenxra/roadpulse-ai/tree/main/frontend/app/roads"
click node_processing_ui "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/processing/page.tsx"
click node_authority_ui "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/authority/page.tsx"
click node_reports_ui "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/reports/page.tsx"
click node_map_component "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/components/MapComponent.tsx"
click node_week_state "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/context/WeekContext.tsx"
click node_api_client "https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/lib/api.ts"
click node_video_processing "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/processing.py"
click node_detection "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/detection_service.py"
click node_ingest_api "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/ingest.py"
click node_clustering "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/aggregation_service.py"
click node_scoring "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/scoring_service.py"
click node_roads_api "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/roads.py"
click node_metrics_api "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/metrics.py"
click node_backend_app "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/main.py"
click node_database "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/models/database.py"
click node_road_geometry "https://github.com/ghanenxra/roadpulse-ai/tree/main/backend/data"
click node_sla "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/authority.py"
click node_verification "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/verification_service.py"
click node_reports "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/report_service.py"
click node_reports_api "https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/reports.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_map_ui,node_road_ui,node_processing_ui,node_authority_ui,node_reports_ui,node_map_component,node_week_state,node_api_client,node_municipal_user toneBlue
class node_video_processing,node_detection,node_ingest_api,node_clustering,node_scoring,node_road_geometry toneAmber
class node_sla,node_verification,node_reports,node_reports_api toneMint
class node_roads_api,node_metrics_api,node_backend_app,node_database toneRose
class node_osrm,node_authorities toneIndigo
```

## Components

### Dashboard

- [Dashboard views](https://github.com/ghanenxra/roadpulse-ai/tree/main/frontend/app): `frontend/app`
- [Road health map](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/map/page.tsx): `frontend/app/map/page.tsx`
- [Road details](https://github.com/ghanenxra/roadpulse-ai/tree/main/frontend/app/roads): `frontend/app/roads`
- [Processing center](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/processing/page.tsx): `frontend/app/processing/page.tsx`
- [Authority tracker](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/authority/page.tsx): `frontend/app/authority/page.tsx`
- [Reports view](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/app/reports/page.tsx): `frontend/app/reports/page.tsx`
- [Interactive map](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/components/MapComponent.tsx): `frontend/components/MapComponent.tsx`
- [Week selection](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/context/WeekContext.tsx): `frontend/context/WeekContext.tsx`
- [API client](https://github.com/ghanenxra/roadpulse-ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Capture and Analysis

- [Video processing](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/processing.py): `backend/api/processing.py`
- [Defect inference](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/detection_service.py): `backend/services/detection_service.py`
- [Detection ingestion](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/ingest.py): `backend/api/ingest.py`
- [Spatial deduplication](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/aggregation_service.py): `backend/services/aggregation_service.py`
- [Risk scoring](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/scoring_service.py): `backend/services/scoring_service.py`
- [Road snapping](https://github.com/ghanenxra/roadpulse-ai/tree/main/backend/data): `backend/data`

### Repair Accountability

- [Issue and SLA tracking](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/authority.py): `backend/api/authority.py`
- [Repair verification](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/verification_service.py): `backend/services/verification_service.py`
- [PDF and CSV exports](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/services/report_service.py): `backend/services/report_service.py`
- [Reports API](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/reports.py): `backend/api/reports.py`

### API and State

- [Road data API](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/roads.py): `backend/api/roads.py`
- [Metrics API](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/api/metrics.py): `backend/api/metrics.py`
- [FastAPI application](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/main.py): `backend/main.py`
- [Road health records](https://github.com/ghanenxra/roadpulse-ai/blob/main/backend/models/database.py): `backend/models/database.py`

### Other components

- **Municipal user**
- **OSRM service**
- **Municipal authorities**

## Connections

- 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