# bilodhi356-ctrl/road-defect-reporting-routing-platform architecture

> Architecture diagram of the GitHub repository bilodhi356-ctrl/road-defect-reporting-routing-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bilodhi356-ctrl/road-defect-reporting-routing-platform
- Repository: https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform

## Overview

This is a KeRRA rural-road defect reporting and routing platform. Citizens submit defect details and GPS locations, receive a reference, and can track report status; staff authenticate to review, assign, update, comment on, and document repairs. Coordinators and administrators also have office-scoped analytics and staff-account management. The graph includes the browser entry points and key routing, persistence, and integration layers. Browser-to-API calls and email-provider wiring are not established by the sampled excerpts, so those links are omitted or marked unverified.

Main entry points: [`server.js`](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/server.js) (HTTP server), [`src/routes/reports.js`](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/reports.js) (Report API), [`src/routes/staff.js`](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/staff.js) (Staff API), [`src/models/User.js`](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/models/User.js) (Staff accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen reporting"]
  node_report_ui["Report submission<br/>[report.js]"]
  node_tracking_ui["Report tracking<br/>[track.js]"]
end

subgraph group_staff["Staff operations"]
  node_login_ui["Staff login<br/>[login.js]"]
  node_dashboard_ui["Staff dashboard<br/>[dashboard.js]"]
  node_entry_ui["Dashboard entry<br/>[dashboard-entry.js]"]
end

subgraph group_backend["API and domain"]
  node_server["HTTP server<br/>[server.js]"]
  node_auth_routes["Authentication API<br/>[auth.js]"]
  node_report_routes["Report API<br/>[reports.js]"]
  node_staff_routes["Staff API<br/>[staff.js]"]
  node_auth_middleware["Authentication checks<br/>[auth.js]"]
  node_rate_limit["Request limiting<br/>[rateLimit.js]"]
  node_validation["Report validation<br/>[validation.js]"]
  node_routing["County routing<br/>[routing.js]"]
end

subgraph group_infra["Data and integrations"]
  node_report_model["Report records<br/>[Report.js]"]
  node_user_model["Staff accounts<br/>[User.js]"]
  node_db_connector["Database connection<br/>[db.js]"]
  node_mongo[("MongoDB")]
  node_image_storage["Image storage<br/>[storage.js]"]
  node_cloudinary[("Cloudinary")]
  node_email_service["Citizen email updates<br/>[email.js]"]
  node_boundary_service["County boundary service"]
end

node_citizen_actor(("Citizen"))

node_server -->|"connects database"| node_db_connector
node_db_connector -->|"connects to"| node_mongo
node_server -->|"mounts auth API"| node_auth_routes
node_server -->|"mounts report API"| node_report_routes
node_server -->|"mounts staff API"| node_staff_routes
node_server -->|"limits requests"| node_rate_limit
node_server -->|"loads boundaries"| node_routing
node_routing -->|"fetches boundaries"| node_boundary_service
node_auth_routes -->|"looks up account"| node_user_model
node_report_routes -->|"checks staff access"| node_auth_middleware
node_staff_routes -->|"checks staff access"| node_auth_middleware
node_auth_middleware -->|"loads account"| node_user_model
node_report_routes -->|"validates input"| node_validation
node_report_routes -->|"routes location"| node_routing
node_report_routes -->|"reads and updates"| node_report_model
node_report_routes -->|"checks assignees"| node_user_model
node_staff_routes -->|"manages accounts"| node_user_model
node_staff_routes -->|"aggregates reports"| node_report_model
node_report_routes -->|"uploads photos"| node_image_storage
node_image_storage -->|"uploads images"| node_cloudinary
node_report_routes -->|"sends updates"| node_email_service
node_server -->|"serves script"| node_report_ui
node_server -->|"serves script"| node_tracking_ui
node_server -->|"serves script"| node_login_ui
node_server -->|"serves script"| node_dashboard_ui
node_server -->|"serves script"| node_entry_ui
node_citizen_actor -.->|"submits report"| node_report_ui
node_citizen_actor -.->|"tracks report"| node_tracking_ui
node_login_ui -.->|"requests login"| node_auth_routes
node_dashboard_ui -.->|"requests reports"| node_report_routes
node_dashboard_ui -.->|"requests staff data"| node_staff_routes

click node_report_ui "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/report.js"
click node_tracking_ui "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/track.js"
click node_login_ui "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/login.js"
click node_dashboard_ui "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/dashboard.js"
click node_entry_ui "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/dashboard-entry.js"
click node_server "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/server.js"
click node_auth_routes "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/auth.js"
click node_report_routes "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/reports.js"
click node_staff_routes "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/staff.js"
click node_auth_middleware "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/middleware/auth.js"
click node_rate_limit "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/middleware/rateLimit.js"
click node_validation "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/utils/validation.js"
click node_routing "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/utils/routing.js"
click node_report_model "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/models/Report.js"
click node_user_model "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/models/User.js"
click node_db_connector "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/db.js"
click node_image_storage "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/services/storage.js"
click node_email_service "https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/services/email.js"

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_report_ui,node_tracking_ui toneBlue
class node_login_ui,node_dashboard_ui,node_entry_ui toneAmber
class node_server,node_auth_routes,node_report_routes,node_staff_routes,node_auth_middleware,node_rate_limit,node_validation,node_routing toneMint
class node_report_model,node_user_model,node_db_connector,node_mongo,node_image_storage,node_cloudinary,node_email_service,node_boundary_service toneRose
class node_citizen_actor toneIndigo
```

## Components

### Citizen reporting

- [Report submission](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/report.js): `report.js`
- [Report tracking](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/track.js): `track.js`

### Staff operations

- [Staff login](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/login.js): `login.js`
- [Staff dashboard](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/dashboard.js): `dashboard.js`
- [Dashboard entry](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/dashboard-entry.js): `dashboard-entry.js`

### API and domain

- [HTTP server](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/server.js): `server.js`
- [Authentication API](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/auth.js): `src/routes/auth.js`
- [Report API](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/reports.js): `src/routes/reports.js`
- [Staff API](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/routes/staff.js): `src/routes/staff.js`
- [Authentication checks](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/middleware/auth.js): `src/middleware/auth.js`
- [Request limiting](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/middleware/rateLimit.js): `src/middleware/rateLimit.js`
- [Report validation](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/utils/validation.js): `src/utils/validation.js`
- [County routing](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/utils/routing.js): `src/utils/routing.js`

### Data and integrations

- [Report records](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/models/Report.js): `src/models/Report.js`
- [Staff accounts](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/models/User.js): `src/models/User.js`
- [Database connection](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/db.js): `src/db.js`
- **MongoDB**
- [Image storage](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/services/storage.js): `src/services/storage.js`
- **Cloudinary**
- [Citizen email updates](https://github.com/bilodhi356-ctrl/road-defect-reporting-routing-platform/blob/main/src/services/email.js): `src/services/email.js`
- **County boundary service**

### Other components

- **Citizen**

## Connections

- HTTP server → Database connection: connects database (evidence: `server.js`)
- Database connection → MongoDB: connects to (evidence: `src/db.js`)
- HTTP server → Authentication API: mounts auth API (evidence: `server.js`)
- HTTP server → Report API: mounts report API (evidence: `server.js`)
- HTTP server → Staff API: mounts staff API (evidence: `server.js`)
- HTTP server → Request limiting: limits requests (evidence: `server.js`)
- HTTP server → County routing: loads boundaries (evidence: `server.js`)
- County routing → County boundary service: fetches boundaries (evidence: `src/utils/routing.js`)
- Authentication API → Staff accounts: looks up account (evidence: `src/routes/auth.js`)
- Report API → Authentication checks: checks staff access (evidence: `src/routes/reports.js`)
- Staff API → Authentication checks: checks staff access (evidence: `src/routes/staff.js`)
- Authentication checks → Staff accounts: loads account (evidence: `src/middleware/auth.js`)
- Report API → Report validation: validates input (evidence: `src/routes/reports.js`)
- Report API → County routing: routes location (evidence: `src/routes/reports.js`)
- Report API → Report records: reads and updates (evidence: `src/routes/reports.js`)
- Report API → Staff accounts: checks assignees (evidence: `src/routes/reports.js`)
- Staff API → Staff accounts: manages accounts (evidence: `src/routes/staff.js`)
- Staff API → Report records: aggregates reports (evidence: `src/routes/staff.js`)
- Report API → Image storage: uploads photos (evidence: `src/routes/reports.js`)
- Image storage → Cloudinary: uploads images (evidence: `src/services/storage.js`)
- Report API → Citizen email updates: sends updates (evidence: `src/routes/reports.js`)
- HTTP server → Report submission: serves script (evidence: `server.js`)
- HTTP server → Report tracking: serves script (evidence: `server.js`)
- HTTP server → Staff login: serves script (evidence: `server.js`)
- HTTP server → Staff dashboard: serves script (evidence: `server.js`)
- HTTP server → Dashboard entry: serves script (evidence: `server.js`)
- Citizen → Report submission: submits report
- Citizen → Report tracking: tracks report
- Staff login → Authentication API: requests login
- Staff dashboard → Report API: requests reports
- Staff dashboard → Staff API: requests staff data