# raga2629/roadpulse_project architecture

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

- Interactive diagram: https://gitdiagram.com/raga2629/roadpulse_project
- Repository: https://github.com/raga2629/roadpulse_project

## Overview

RoadPulse lets citizens report road damage and track its status, while administrators triage reports, coordinate maintenance, and confirm repairs. The main workflow runs from the React client through FastAPI routes to report and road-issue services, with AI detection and repair verification supporting assessment. The README also describes a public map and dashboards. Edges reflect shown route registration, imports, or documented capabilities; frontend-to-backend calls are not fully evidenced in the excerpts, so that boundary is left unconnected.

Main entry points: [`frontend/src/App.jsx`](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/App.jsx) (App routing), [`backend/app/database/session.py`](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/database/session.py) (SQL database), [`backend/app/main.py`](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/main.py) (API application), [`backend/app/services/report_service.py`](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/report_service.py) (Report service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React application"]
  node_app["App routing<br/>[App.jsx]"]
  node_newreport["Submit report<br/>[NewReport.jsx]"]
  node_clientapi["API client<br/>[api.js]"]
  node_map["Issue map<br/>[MapPage.jsx]"]
  node_adminreport["Report review<br/>[ReportDetail.jsx]"]
  node_authstate["Auth state<br/>[useAuth.jsx]"]
end

subgraph group_api["API and workflows"]
  node_fastapi["API application<br/>[main.py]"]
  node_reports["Report routes<br/>[reports.py]"]
  node_detectionroutes["Detection routes<br/>[detection.py]"]
  node_maproutes["Map routes<br/>[map_routes.py]"]
  node_roadissues["Road issue service"]
  node_reportservice["Report service<br/>[report_service.py]"]
  node_repair["Repair verification"]
  node_priority["Priority scoring"]
  node_storage["Upload storage<br/>[storage_service.py]"]
end

subgraph group_vision["AI assessment"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_detector["Damage detector<br/>[detector.py]"]
  node_severity["Severity estimator<br/>[severity.py]"]
end

subgraph group_data["Persistence"]
  node_database[("SQL database<br/>[session.py]")]
  node_reportmodel["Report records<br/>[report.py]"]
  node_roadmodel["Road issue records<br/>[road_issue.py]"]
  node_usermodel["User records<br/>[user.py]"]
end

node_citizen(("Citizen"))
node_admin(("Administrator"))

node_citizen -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes to"| node_newreport
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_adminreport
node_app -->|"checks auth"| node_authstate
node_newreport -->|"submits through"| node_clientapi
node_map -->|"fetches through"| node_clientapi
node_adminreport -->|"fetches through"| node_clientapi
node_fastapi -->|"registers"| node_reports
node_fastapi -->|"registers"| node_detectionroutes
node_fastapi -->|"registers"| node_maproutes
node_ai_service -->|"loads"| node_detector
node_detector -->|"estimates"| node_severity
node_maproutes -->|"scores markers"| node_priority
node_reportservice -->|"stores uploads"| node_storage
node_reportservice -.->|"requests analysis"| node_ai_service
node_roadissues -->|"calculates priority"| node_priority
node_repair -->|"analyzes evidence"| node_ai_service
node_repair -->|"uses storage"| node_storage
node_reportservice -.->|"reads and writes"| node_database
node_roadissues -.->|"reads and writes"| node_database
node_repair -.->|"reads and writes"| node_database
node_database -->|"maps records"| node_reportmodel
node_database -->|"maps records"| node_roadmodel
node_database -->|"maps records"| node_usermodel

click node_app "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/App.jsx"
click node_newreport "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/citizen/NewReport.jsx"
click node_clientapi "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/services/api.js"
click node_map "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/MapPage.jsx"
click node_adminreport "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/admin/ReportDetail.jsx"
click node_authstate "https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/hooks/useAuth.jsx"
click node_fastapi "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/main.py"
click node_reports "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/reports.py"
click node_detectionroutes "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/detection.py"
click node_maproutes "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/map_routes.py"
click node_roadissues "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/road_issue_service.py"
click node_reportservice "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/report_service.py"
click node_repair "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/repair_verification_service.py"
click node_priority "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/priority_service.py"
click node_storage "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/storage_service.py"
click node_ai_service "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/ai_service.py"
click node_detector "https://github.com/raga2629/roadpulse_project/blob/main/ai/detector.py"
click node_severity "https://github.com/raga2629/roadpulse_project/blob/main/ai/severity.py"
click node_database "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/database/session.py"
click node_reportmodel "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/report.py"
click node_roadmodel "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/road_issue.py"
click node_usermodel "https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/user.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_app,node_newreport,node_clientapi,node_map,node_adminreport,node_authstate toneBlue
class node_fastapi,node_reports,node_detectionroutes,node_maproutes,node_roadissues,node_reportservice,node_repair,node_priority,node_storage toneAmber
class node_ai_service,node_detector,node_severity toneMint
class node_database,node_reportmodel,node_roadmodel,node_usermodel toneRose
class node_citizen,node_admin toneIndigo
```

## Components

### React application

- [App routing](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Submit report](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/citizen/NewReport.jsx): `frontend/src/pages/citizen/NewReport.jsx`
- [API client](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Issue map](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/MapPage.jsx): `frontend/src/pages/MapPage.jsx`
- [Report review](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/pages/admin/ReportDetail.jsx): `frontend/src/pages/admin/ReportDetail.jsx`
- [Auth state](https://github.com/raga2629/roadpulse_project/blob/main/frontend/src/hooks/useAuth.jsx): `frontend/src/hooks/useAuth.jsx`

### API and workflows

- [API application](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/main.py): `backend/app/main.py`
- [Report routes](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/reports.py): `backend/app/routes/reports.py`
- [Detection routes](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/detection.py): `backend/app/routes/detection.py`
- [Map routes](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/routes/map_routes.py): `backend/app/routes/map_routes.py`
- [Road issue service](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/road_issue_service.py): `backend/app/services/road_issue_service.py`
- [Report service](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`
- [Repair verification](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/repair_verification_service.py): `backend/app/services/repair_verification_service.py`
- [Priority scoring](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/priority_service.py): `backend/app/services/priority_service.py`
- [Upload storage](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`

### AI assessment

- [AI service](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Damage detector](https://github.com/raga2629/roadpulse_project/blob/main/ai/detector.py): `ai/detector.py`
- [Severity estimator](https://github.com/raga2629/roadpulse_project/blob/main/ai/severity.py): `ai/severity.py`

### Persistence

- [SQL database](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Report records](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/report.py): `backend/app/models/report.py`
- [Road issue records](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/road_issue.py): `backend/app/models/road_issue.py`
- [User records](https://github.com/raga2629/roadpulse_project/blob/main/backend/app/models/user.py): `backend/app/models/user.py`

### Other components

- **Citizen**
- **Administrator**

## Connections

- Citizen → App routing: uses (evidence: `README.md`)
- Administrator → App routing: uses (evidence: `README.md`)
- App routing → Submit report: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Issue map: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Report review: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Auth state: checks auth (evidence: `frontend/src/App.jsx`)
- Submit report → API client: submits through (evidence: `frontend/src/pages/citizen/NewReport.jsx`)
- Issue map → API client: fetches through (evidence: `frontend/src/pages/MapPage.jsx`)
- Report review → API client: fetches through (evidence: `frontend/src/pages/admin/ReportDetail.jsx`)
- API application → Report routes: registers (evidence: `backend/app/main.py`)
- API application → Detection routes: registers (evidence: `backend/app/main.py`)
- API application → Map routes: registers (evidence: `backend/app/main.py`)
- AI service → Damage detector: loads (evidence: `backend/app/services/ai_service.py`)
- Damage detector → Severity estimator: estimates (evidence: `ai/detector.py`)
- Map routes → Priority scoring: scores markers (evidence: `backend/app/routes/map_routes.py`)
- Report service → Upload storage: stores uploads (evidence: `backend/app/services/report_service.py`)
- Report service → AI service: requests analysis
- Road issue service → Priority scoring: calculates priority (evidence: `backend/app/services/road_issue_service.py`)
- Repair verification → AI service: analyzes evidence (evidence: `backend/app/services/repair_verification_service.py`)
- Repair verification → Upload storage: uses storage (evidence: `backend/app/services/repair_verification_service.py`)
- Report service → SQL database: reads and writes
- Road issue service → SQL database: reads and writes
- Repair verification → SQL database: reads and writes
- SQL database → Report records: maps records (evidence: `backend/app/models/report.py`)
- SQL database → Road issue records: maps records (evidence: `backend/app/models/road_issue.py`)
- SQL database → User records: maps records (evidence: `backend/app/models/user.py`)