# pratikshark25/pothole_web architecture

> Architecture diagram of the GitHub repository pratikshark25/pothole_web, 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/pratikshark25/pothole_web
- Repository: https://github.com/pratikshark25/pothole_web

## Overview

Pothole Mapper is a role-based web app for commuters to report road damage and for municipal staff to track repairs. The main path runs from a commuter’s report through server-side image validation and location handling into a pothole record, which map and dashboard views expose for follow-up. Authentication, administrative user management, and commuter rewards are supporting capabilities. The README also describes cloud image storage and AI verification; the sampled upload code shows Roboflow validation, but does not establish cloud-storage integration. Edges to external services are limited to documented or excerpted behavior.

Main entry points: [`server/routes/reportroute.js`](https://github.com/pratikshark25/pothole_web/blob/main/server/routes/reportroute.js) (Report endpoints), [`client/src/App.jsx`](https://github.com/pratikshark25/pothole_web/blob/main/client/src/App.jsx) (App routing), [`server/routes/auth.js`](https://github.com/pratikshark25/pothole_web/blob/main/server/routes/auth.js) (Auth endpoints), [`server/models/User.js`](https://github.com/pratikshark25/pothole_web/blob/main/server/models/User.js) (User records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_home["Home page<br/>[HomePage.jsx]"]
  node_report_ui["Report form<br/>[ReportPothole.jsx]"]
  node_map_ui["Pothole map<br/>[PotholeMap.jsx]"]
  node_commuter_dash["Commuter dashboard<br/>[Dashboard.jsx]"]
  node_municipal_dash["Municipal dashboard"]
  node_admin_dash["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_profile["Profile<br/>[Profile.jsx]"]
  node_team["Team page<br/>[TeamPage.jsx]"]
end

subgraph group_identity["Identity and access"]
  node_auth_context["Auth state<br/>[AuthContext.jsx]"]
  node_auth_ui["Login and signup<br/>[AuthModal.jsx]"]
  node_otp["OTP recovery<br/>[OTPInput.jsx]"]
  node_reset["Password reset<br/>[Reset.jsx]"]
  node_api_config["API configuration<br/>[api.js]"]
  node_auth_routes["Auth endpoints<br/>[auth.js]"]
  node_auth_middleware["Auth middleware<br/>[auth.js]"]
end

subgraph group_reporting["Reporting and repairs"]
  node_server["Express server<br/>[server.js]"]
  node_report_routes["Report endpoints<br/>[reportroute.js]"]
  node_roboflow{{"Roboflow detection"}}
  node_ocr["Image GPS OCR<br/>[reportroute.js]"]
end

subgraph group_persistence["Data and rewards"]
  node_user_model[("User records<br/>[User.js]")]
  node_pothole_model[("Pothole records<br/>[Pothole.js]")]
  node_rewards["Reward calculations<br/>[rewards.js]"]
  node_mongo[("MongoDB")]
end

node_commuter(("Commuter"))

node_commuter -->|"opens app"| node_home
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_report_ui
node_app -->|"routes to"| node_map_ui
node_app -->|"routes to"| node_commuter_dash
node_app -->|"routes to"| node_municipal_dash
node_app -->|"routes to"| node_admin_dash
node_app -->|"routes to"| node_profile
node_app -->|"routes to"| node_team
node_home -->|"opens"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_auth_context
node_auth_context -->|"uses API base"| node_api_config
node_otp -->|"uses API base"| node_api_config
node_reset -->|"uses API base"| node_api_config
node_auth_context -->|"calls auth API"| node_auth_routes
node_report_ui -->|"submits report"| node_report_routes
node_map_ui -->|"fetches potholes"| node_report_routes
node_commuter_dash -->|"fetches reports"| node_report_routes
node_municipal_dash -->|"fetches repair data"| node_report_routes
node_admin_dash -->|"manages users"| node_auth_routes
node_server -->|"mounts routes"| node_auth_routes
node_server -->|"mounts routes"| node_report_routes
node_server -->|"connects before serving"| node_mongo
node_report_routes -->|"validates image"| node_roboflow
node_report_routes -->|"extracts coordinates"| node_ocr
node_report_routes -->|"saves and queries"| node_pothole_model
node_report_routes -->|"assigns staff"| node_user_model
node_report_routes -->|"updates rewards"| node_rewards
node_auth_routes -->|"guards admin routes"| node_auth_middleware
node_auth_middleware -->|"loads user"| node_user_model
node_auth_routes -->|"reads and writes"| node_user_model
node_auth_routes -->|"calculates profile level"| node_rewards
node_pothole_model -->|"persists records"| node_mongo
node_user_model -->|"persists accounts"| node_mongo
node_report_routes -.->|"AI verification"| node_roboflow
node_report_routes -.->|"stores report image"| node_mongo

click node_app "https://github.com/pratikshark25/pothole_web/blob/main/client/src/App.jsx"
click node_home "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/HomePage.jsx"
click node_report_ui "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/ReportPothole.jsx"
click node_map_ui "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/PotholeMap.jsx"
click node_commuter_dash "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/Dashboard.jsx"
click node_municipal_dash "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/municipal/MunicipalDashboard.jsx"
click node_admin_dash "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/admin/AdminDashboard.jsx"
click node_profile "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/Profile.jsx"
click node_team "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/TeamPage.jsx"
click node_auth_context "https://github.com/pratikshark25/pothole_web/blob/main/client/src/context/AuthContext.jsx"
click node_auth_ui "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/AuthModal.jsx"
click node_otp "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/OTPInput.jsx"
click node_reset "https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/Reset.jsx"
click node_api_config "https://github.com/pratikshark25/pothole_web/blob/main/client/src/config/api.js"
click node_server "https://github.com/pratikshark25/pothole_web/blob/main/server/server.js"
click node_auth_routes "https://github.com/pratikshark25/pothole_web/blob/main/server/routes/auth.js"
click node_auth_middleware "https://github.com/pratikshark25/pothole_web/blob/main/server/middleware/auth.js"
click node_report_routes "https://github.com/pratikshark25/pothole_web/blob/main/server/routes/reportroute.js"
click node_ocr "https://github.com/pratikshark25/pothole_web/blob/main/server/routes/reportroute.js"
click node_user_model "https://github.com/pratikshark25/pothole_web/blob/main/server/models/User.js"
click node_pothole_model "https://github.com/pratikshark25/pothole_web/blob/main/server/models/Pothole.js"
click node_rewards "https://github.com/pratikshark25/pothole_web/blob/main/server/utils/rewards.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_app,node_home,node_report_ui,node_map_ui,node_commuter_dash,node_municipal_dash,node_admin_dash,node_profile,node_team toneBlue
class node_auth_context,node_auth_ui,node_otp,node_reset,node_api_config,node_auth_routes,node_auth_middleware toneAmber
class node_server,node_report_routes,node_roboflow,node_ocr toneMint
class node_user_model,node_pothole_model,node_rewards,node_mongo toneRose
class node_commuter toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/pratikshark25/pothole_web/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Home page](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/HomePage.jsx): `client/src/components/HomePage.jsx`
- [Report form](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/ReportPothole.jsx): `client/src/components/ReportPothole.jsx`
- [Pothole map](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/PotholeMap.jsx): `client/src/components/PotholeMap.jsx`
- [Commuter dashboard](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/Dashboard.jsx): `client/src/components/Dashboard.jsx`
- [Municipal dashboard](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/municipal/MunicipalDashboard.jsx): `client/src/components/municipal/MunicipalDashboard.jsx`
- [Admin dashboard](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/admin/AdminDashboard.jsx): `client/src/components/admin/AdminDashboard.jsx`
- [Profile](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/Profile.jsx): `client/src/components/Profile.jsx`
- [Team page](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/TeamPage.jsx): `client/src/components/TeamPage.jsx`

### Identity and access

- [Auth state](https://github.com/pratikshark25/pothole_web/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [Login and signup](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/AuthModal.jsx): `client/src/components/auth/AuthModal.jsx`
- [OTP recovery](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/OTPInput.jsx): `client/src/components/auth/OTPInput.jsx`
- [Password reset](https://github.com/pratikshark25/pothole_web/blob/main/client/src/components/auth/Reset.jsx): `client/src/components/auth/Reset.jsx`
- [API configuration](https://github.com/pratikshark25/pothole_web/blob/main/client/src/config/api.js): `client/src/config/api.js`
- [Auth endpoints](https://github.com/pratikshark25/pothole_web/blob/main/server/routes/auth.js): `server/routes/auth.js`
- [Auth middleware](https://github.com/pratikshark25/pothole_web/blob/main/server/middleware/auth.js): `server/middleware/auth.js`

### Reporting and repairs

- [Express server](https://github.com/pratikshark25/pothole_web/blob/main/server/server.js): `server/server.js`
- [Report endpoints](https://github.com/pratikshark25/pothole_web/blob/main/server/routes/reportroute.js): `server/routes/reportroute.js`
- **Roboflow detection**
- [Image GPS OCR](https://github.com/pratikshark25/pothole_web/blob/main/server/routes/reportroute.js): `server/routes/reportroute.js`

### Data and rewards

- [User records](https://github.com/pratikshark25/pothole_web/blob/main/server/models/User.js): `server/models/User.js`
- [Pothole records](https://github.com/pratikshark25/pothole_web/blob/main/server/models/Pothole.js): `server/models/Pothole.js`
- [Reward calculations](https://github.com/pratikshark25/pothole_web/blob/main/server/utils/rewards.js): `server/utils/rewards.js`
- **MongoDB**

### Other components

- **Commuter**

## Connections

- Commuter → Home page: opens app
- App routing → Home page: routes to (evidence: `client/src/App.jsx`)
- App routing → Report form: routes to (evidence: `client/src/App.jsx`)
- App routing → Pothole map: routes to (evidence: `client/src/App.jsx`)
- App routing → Commuter dashboard: routes to (evidence: `client/src/App.jsx`)
- App routing → Municipal dashboard: routes to (evidence: `client/src/App.jsx`)
- App routing → Admin dashboard: routes to (evidence: `client/src/App.jsx`)
- App routing → Profile: routes to (evidence: `client/src/App.jsx`)
- App routing → Team page: routes to (evidence: `client/src/App.jsx`)
- Home page → Login and signup: opens (evidence: `client/src/components/HomePage.jsx`)
- Login and signup → Auth state: submits credentials (evidence: `client/src/components/auth/AuthModal.jsx`)
- Auth state → API configuration: uses API base (evidence: `client/src/context/AuthContext.jsx`)
- OTP recovery → API configuration: uses API base (evidence: `client/src/config/api.js`)
- Password reset → API configuration: uses API base (evidence: `client/src/config/api.js`)
- Auth state → Auth endpoints: calls auth API (evidence: `client/src/context/AuthContext.jsx`)
- Report form → Report endpoints: submits report (evidence: `README.md`)
- Pothole map → Report endpoints: fetches potholes (evidence: `README.md`)
- Commuter dashboard → Report endpoints: fetches reports (evidence: `README.md`)
- Municipal dashboard → Report endpoints: fetches repair data (evidence: `README.md`)
- Admin dashboard → Auth endpoints: manages users (evidence: `server/routes/auth.js`)
- Express server → Auth endpoints: mounts routes (evidence: `server/server.js`)
- Express server → Report endpoints: mounts routes (evidence: `server/server.js`)
- Express server → MongoDB: connects before serving (evidence: `server/server.js`)
- Report endpoints → Roboflow detection: validates image (evidence: `server/routes/reportroute.js`)
- Report endpoints → Image GPS OCR: extracts coordinates (evidence: `server/routes/reportroute.js`)
- Report endpoints → Pothole records: saves and queries (evidence: `server/routes/reportroute.js`)
- Report endpoints → User records: assigns staff (evidence: `server/routes/reportroute.js`)
- Report endpoints → Reward calculations: updates rewards (evidence: `server/routes/reportroute.js`)
- Auth endpoints → Auth middleware: guards admin routes (evidence: `server/routes/auth.js`)
- Auth middleware → User records: loads user (evidence: `server/middleware/auth.js`)
- Auth endpoints → User records: reads and writes (evidence: `server/routes/auth.js`)
- Auth endpoints → Reward calculations: calculates profile level (evidence: `server/routes/auth.js`)
- Pothole records → MongoDB: persists records (evidence: `README.md`)
- User records → MongoDB: persists accounts (evidence: `README.md`)
- Report endpoints → Roboflow detection: AI verification (evidence: `README.md`)
- Report endpoints → MongoDB: stores report image (evidence: `README.md`)