How shivam200669/smart-pothole works
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: complaints.js Complaints API · Services Services · api.js API Client · auth.js Auth API
Components 19
React Web
Vite + React browser client
- Web App · Browser client entry and top-level shell
frontend/src/App.jsx - Bootstrap · Mounts the React application
frontend/src/main.jsx - API Client · Centralized backend requests for the web app
frontend/src/services/api.js - Pages · Login, signup, dashboard, admin, and worker management screens
frontend/src/pages - UI Parts · Layout, stats, report cards, forms, and map widgets
frontend/src/components
SwiftUI iOS
Mobile client with MVVM and device services
- iOS App · Mobile client entry and root application
ios/SmartPotholeApp.swift - Views · Auth, dashboard, map, and report creation screens
ios/Views - ViewModels · Auth, dashboard, map, and report orchestration
ios/ViewModels - Models · Report, user, and worker data structures
ios/Models - Services · Backend API access and device location capture
ios/Services
Express Backend
REST API and protected server-side domain logic
- Server · Main backend process and API host
backend/server.js - Auth API · Login and signup endpoints
backend/routes/auth.js - Complaints API · Complaint and report endpoints
backend/routes/complaints.js - Workers API · Worker management endpoints
backend/routes/workers.js - Auth Guard · Protects privileged backend routes
backend/middleware/authMiddleware.js - DB Config · Backend database connection/configuration
backend/config/db.js
Connections 28
- 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