# shivam200669/smart-pothole architecture

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

- Interactive diagram: https://gitdiagram.com/shivam200669/smart-pothole
- Repository: https://github.com/shivam200669/smart-pothole

## Overview

1. **High-level shape**
   - This is a three-client system around one REST backend: a **React web app**, a **SwiftUI iOS app**, and a **Node/Express API**.
   - Both clients talk to the same backend over HTTP and share the same domain concepts: users, complaints/reports, workers, and map/location data.

2. **Backend as the system hub**
   - The backend lives under `backend/` and is the central integration point.
   - `backend/server.js` is the main Express entrypoint.
   - API surface is split into route modules: `routes/auth.js`, `routes/complaints.js`, and `routes/workers.js`.
   - This suggests a clean boundary between authentication, complaint handling, and worker management.

3. **Backend security boundary**
   - `middleware/authMiddleware.js` indicates protected routes behind an auth check.
   - The architecture likely has public endpoints for login/signup and authenticated endpoints for complaint operations, worker admin actions, and user-specific data.
   - For a diagram, show auth as a gate between clients and privileged backend resources.

4. **Backend persistence and file storage**
   - The checked-in storage artifacts are SQLite databases: `database.sqlite`, `database_v2.sqlite`, `database_v3.sqlite`, `database_v4.sqlite`, plus `schema.sql`.
   - Even though the README mentions MySQL, the repository currently looks implemented around **SQLite** for local persistence or snapshots/migrations.
   - `backend/uploads/` is a separate file boundary for image or attachment storage tied to pothole reports.

5. **Web frontend structure**
   - The web client is a Vite + React app in `frontend/`.
   - `src/main.jsx` and `src/App.jsx` bootstrap the SPA, while `src/services/api.js` centralizes backend calls.
   - `pages/` contains the major route-level screens: `Login`, `Signup`, `Dashboard`, `AdminDashboard`, and `ManageWorkers`.

6. **Web UI composition**
   - Reusable UI lives in `components/`, organized by concern:
     - `Layout/` for app shell, navbar, and sidebar
     - `Dashboard/StatCard.jsx` for analytics tiles
     - `Report/ReportCard.jsx` and `ReportForm.jsx` for complaint submission and display
     - `MapComponent.jsx` for map rendering
   - This implies the web app is a role-based dashboard with shared layout and feature widgets rather than a simple single-page form.

7. **Web data flow**
   - User actions in the React pages/components call `services/api.js`.
   - API responses populate dashboards, complaint lists, worker management screens, and map views.
   - Images and location-enabled reports likely flow from the report form to the backend, then into the database and uploads storage.

8. **iOS app architecture**
   - The iOS app uses **SwiftUI + MVVM**.
   - `Models/` holds domain objects (`Report`, `User`, `Worker`).
   - `ViewModels/` separates state and orchestration (`AuthViewModel`, `DashboardViewModel`, `MapViewModel`, `ReportViewModel`).
   - `Views/` contains feature screens for auth, dashboard, map, and new report creation.

9. **iOS service layer**
   - `Services/NetworkManager.swift` is the API boundary to the backend.
   - `Services/LocationManager.swift` is the device-location boundary, feeding GPS data into report creation and map views.
   - This creates a clear chain: SwiftUI view → view model → network/location services → backend API.

10. **Mobile UX and device capabilities**
   - `MapKit` and `Core Location` are called out in the README and align with the `Map` and `LocationManager` code.
   - The iOS app is not just a thin client; it uses device sensors to capture live location for complaints, which is a key architectural dependency.

11. **Shared domain across platforms**
   - The same core workflow appears in all three layers:
     - authenticate a user
     - create or browse pothole reports
     - attach location and image data
     - track status / assignment
     - review summary metrics on dashboards
   - `workers` are a distinct backend entity, surfaced especially in the admin web UI.

12. **Important diagram boundaries**
   - Draw the system as:
     - **Clients:** React web SPA and SwiftUI iOS app
     - **API layer:** Express backend with route modules and auth middleware
     - **Data layer:** SQLite database files plus schema, and separate upload storage
     - **Device services:** iOS location services feeding the mobile report flow
   - The backend should sit between both clients and persistence, while the iOS location manager and web map component remain client-side concerns.

Main entry points: [`backend/routes/complaints.js`](https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/complaints.js) (Complaints API), [`ios/Services`](https://github.com/shivam200669/smart-pothole/tree/main/ios/Services) (Services), [`frontend/src/services/api.js`](https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/services/api.js) (API Client), [`backend/routes/auth.js`](https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/auth.js) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_web["React Web"]
  node_web_app["Web App<br/>React SPA<br/>[App.jsx]"]
  node_web_main["Bootstrap<br/>Vite entry<br/>[main.jsx]"]
  node_web_api["API Client<br/>HTTP service<br/>[api.js]"]
  node_web_pages["Pages<br/>Route screens"]
  node_web_ui["UI Parts<br/>Reusable components"]
end

subgraph group_client_ios["SwiftUI iOS"]
  node_ios_app["iOS App<br/>SwiftUI app"]
  node_ios_views["Views<br/>SwiftUI screens"]
  node_ios_vms["ViewModels<br/>MVVM state"]
  node_ios_models["Models"]
  node_ios_services["Services<br/>Device + network"]
end

subgraph group_backend_api["Express Backend"]
  node_api_server["Server<br/>Express entrypoint<br/>[server.js]"]
  node_auth_routes["Auth API<br/>Route module<br/>[auth.js]"]
  node_complaint_routes["Complaints API<br/>Route module<br/>[complaints.js]"]
  node_worker_routes["Workers API<br/>Route module<br/>[workers.js]"]
  node_auth_mw["Auth Guard<br/>Middleware<br/>[authMiddleware.js]"]
  node_db_config["DB Config<br/>SQLite setup<br/>[db.js]"]
end

subgraph group_data_layer["Data Layer"]
  node_schema["Schema<br/>[schema.sql]"]
  node_sqlite_db[("SQLite DB<br/>Persistent store<br/>[database.sqlite]")]
  node_uploads["Uploads<br/>File storage"]
end

node_web_main -->|"bootstraps"| node_web_app
node_web_app -->|"renders"| node_web_pages
node_web_app -->|"composes"| node_web_ui
node_web_pages -->|"calls"| node_web_api
node_web_ui -->|"calls"| node_web_api
node_ios_app -->|"hosts"| node_ios_views
node_ios_views -->|"binds"| node_ios_vms
node_ios_vms -->|"uses"| node_ios_services
node_ios_vms -->|"maps"| node_ios_models
node_ios_services -->|"HTTP"| node_auth_routes
node_ios_services -->|"HTTP"| node_complaint_routes
node_ios_services -->|"HTTP"| node_worker_routes
node_web_api -->|"HTTP"| node_auth_routes
node_web_api -->|"HTTP"| node_complaint_routes
node_web_api -->|"HTTP"| node_worker_routes
node_api_server -->|"mounts"| node_auth_routes
node_api_server -->|"mounts"| node_complaint_routes
node_api_server -->|"mounts"| node_worker_routes
node_auth_routes -->|"guards"| node_auth_mw
node_complaint_routes -->|"guards"| node_auth_mw
node_worker_routes -->|"guards"| node_auth_mw
node_auth_routes -->|"reads/writes"| node_db_config
node_complaint_routes -->|"reads/writes"| node_db_config
node_worker_routes -->|"reads/writes"| node_db_config
node_db_config -->|"uses"| node_sqlite_db
node_db_config -->|"defined by"| node_schema
node_complaint_routes -->|"stores files"| node_uploads
node_ios_services -.->|"references"| node_uploads

click node_web_app "https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/App.jsx"
click node_web_main "https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/main.jsx"
click node_web_api "https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/services/api.js"
click node_web_pages "https://github.com/shivam200669/smart-pothole/tree/main/frontend/src/pages"
click node_web_ui "https://github.com/shivam200669/smart-pothole/tree/main/frontend/src/components"
click node_ios_app "https://github.com/shivam200669/smart-pothole/blob/main/ios/SmartPotholeApp.swift"
click node_ios_views "https://github.com/shivam200669/smart-pothole/tree/main/ios/Views"
click node_ios_vms "https://github.com/shivam200669/smart-pothole/tree/main/ios/ViewModels"
click node_ios_models "https://github.com/shivam200669/smart-pothole/tree/main/ios/Models"
click node_ios_services "https://github.com/shivam200669/smart-pothole/tree/main/ios/Services"
click node_api_server "https://github.com/shivam200669/smart-pothole/blob/main/backend/server.js"
click node_auth_routes "https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/auth.js"
click node_complaint_routes "https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/complaints.js"
click node_worker_routes "https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/workers.js"
click node_auth_mw "https://github.com/shivam200669/smart-pothole/blob/main/backend/middleware/authMiddleware.js"
click node_db_config "https://github.com/shivam200669/smart-pothole/blob/main/backend/config/db.js"
click node_schema "https://github.com/shivam200669/smart-pothole/blob/main/backend/schema.sql"
click node_sqlite_db "https://github.com/shivam200669/smart-pothole/blob/main/backend/database.sqlite"
click node_uploads "https://github.com/shivam200669/smart-pothole/tree/main/backend/uploads"

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_web_app,node_web_main,node_web_api,node_web_pages,node_web_ui toneBlue
class node_ios_app,node_ios_views,node_ios_vms,node_ios_models,node_ios_services toneAmber
class node_api_server,node_auth_routes,node_complaint_routes,node_worker_routes,node_auth_mw,node_db_config toneMint
class node_schema,node_sqlite_db,node_uploads toneRose
```

## Components

### React Web

Vite + React browser client

- [Web App](https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/App.jsx): React SPA · Browser client entry and top-level shell · `frontend/src/App.jsx`
- [Bootstrap](https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/main.jsx): Vite entry · Mounts the React application · `frontend/src/main.jsx`
- [API Client](https://github.com/shivam200669/smart-pothole/blob/main/frontend/src/services/api.js): HTTP service · Centralized backend requests for the web app · `frontend/src/services/api.js`
- [Pages](https://github.com/shivam200669/smart-pothole/tree/main/frontend/src/pages): Route screens · Login, signup, dashboard, admin, and worker management screens · `frontend/src/pages`
- [UI Parts](https://github.com/shivam200669/smart-pothole/tree/main/frontend/src/components): Reusable components · Layout, stats, report cards, forms, and map widgets · `frontend/src/components`

### SwiftUI iOS

Mobile client with MVVM and device services

- [iOS App](https://github.com/shivam200669/smart-pothole/blob/main/ios/SmartPotholeApp.swift): SwiftUI app · Mobile client entry and root application · `ios/SmartPotholeApp.swift`
- [Views](https://github.com/shivam200669/smart-pothole/tree/main/ios/Views): SwiftUI screens · Auth, dashboard, map, and report creation screens · `ios/Views`
- [ViewModels](https://github.com/shivam200669/smart-pothole/tree/main/ios/ViewModels): MVVM state · Auth, dashboard, map, and report orchestration · `ios/ViewModels`
- [Models](https://github.com/shivam200669/smart-pothole/tree/main/ios/Models): Domain models · Report, user, and worker data structures · `ios/Models`
- [Services](https://github.com/shivam200669/smart-pothole/tree/main/ios/Services): Device + network · Backend API access and device location capture · `ios/Services`

### Express Backend

REST API and protected server-side domain logic

- [Server](https://github.com/shivam200669/smart-pothole/blob/main/backend/server.js): Express entrypoint · Main backend process and API host · `backend/server.js`
- [Auth API](https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/auth.js): Route module · Login and signup endpoints · `backend/routes/auth.js`
- [Complaints API](https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/complaints.js): Route module · Complaint and report endpoints · `backend/routes/complaints.js`
- [Workers API](https://github.com/shivam200669/smart-pothole/blob/main/backend/routes/workers.js): Route module · Worker management endpoints · `backend/routes/workers.js`
- [Auth Guard](https://github.com/shivam200669/smart-pothole/blob/main/backend/middleware/authMiddleware.js): Middleware · Protects privileged backend routes · `backend/middleware/authMiddleware.js`
- [DB Config](https://github.com/shivam200669/smart-pothole/blob/main/backend/config/db.js): SQLite setup · Backend database connection/configuration · `backend/config/db.js`

### Data Layer

Persistent database and uploaded report assets

- [Schema](https://github.com/shivam200669/smart-pothole/blob/main/backend/schema.sql): SQL schema · Database structure definition · `backend/schema.sql`
- [SQLite DB](https://github.com/shivam200669/smart-pothole/blob/main/backend/database.sqlite): Persistent store · Primary repository database snapshots · `backend/database.sqlite`
- [Uploads](https://github.com/shivam200669/smart-pothole/tree/main/backend/uploads): File storage · Stored report images and attachments · `backend/uploads`

## Connections

- Bootstrap → Web App: bootstraps · Entry file mounts the React app
- Web App → Pages: renders · Top-level app routes to feature pages
- Web App → UI Parts: composes · App uses shared UI components
- Pages → API Client: calls · Screens fetch and submit backend data
- UI Parts → API Client: calls · Forms and widgets reuse API requests
- iOS App → Views: hosts · Application root presents SwiftUI screens
- Views → ViewModels: binds · Views delegate state and actions to view models
- ViewModels → Services: uses · View models call network and location services
- ViewModels → Models: maps · View state is built from domain models
- Services → Auth API: HTTP · Mobile client authenticates through the backend
- Services → Complaints API: HTTP · Mobile client creates and browses reports
- Services → Workers API: HTTP · Mobile client can retrieve worker-related data
- API Client → Auth API: HTTP · Web client uses auth endpoints
- API Client → Complaints API: HTTP · Web client uses complaint endpoints
- API Client → Workers API: HTTP · Web admin screens manage workers through the API
- Server → Auth API: mounts · Server registers auth routes
- Server → Complaints API: mounts · Server registers complaint routes
- Server → Workers API: mounts · Server registers worker routes
- Auth API → Auth Guard: guards · Privileged operations are protected by auth middleware
- Complaints API → Auth Guard: guards · Complaint operations require authenticated access
- Workers API → Auth Guard: guards · Worker admin operations require auth checks
- Auth API → DB Config: reads/writes · Auth data persists through the database layer
- Complaints API → DB Config: reads/writes · Reports and status data persist through the database layer
- Workers API → DB Config: reads/writes · Worker records persist through the database layer
- DB Config → SQLite DB: uses · Backend connects to the SQLite database
- DB Config → Schema: defined by · Database structure comes from schema SQL
- Complaints API → Uploads: stores files · Report attachments and images are saved separately
- Services → Uploads: references · Mobile report flow can include image/file payloads handled by backend storage