# ifaz07/shomadhan architecture

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

- Interactive diagram: https://gitdiagram.com/ifaz07/shomadhan
- Repository: https://github.com/ifaz07/shomadhan

## Overview

Shomadhan is a role-based civic issue reporting and resolution platform. Citizens submit and track geolocated complaints; the API triages reports, scores priority, checks duplicates, and stores tickets for officers and city authorities to manage through resolution. Escalation, notifications, analytics, identity review, emergency alerts, and volunteer events form distinct supporting workflows. The diagram combines documented capabilities with relationships visible in sampled files and the source index; unsampled internals are represented at their documented subsystem paths.

Main entry points: [`backend/controllers/complaint.controller.js`](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/complaint.controller.js) (Complaint handling), [`backend/models/Complaint.model.js`](https://github.com/ifaz07/shomadhan/blob/main/backend/models/Complaint.model.js) (Complaint records), [`backend/models/User.model.js`](https://github.com/ifaz07/shomadhan/blob/main/backend/models/User.model.js) (User accounts), [`backend/server.js`](https://github.com/ifaz07/shomadhan/blob/main/backend/server.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["React application<br/>[App.jsx]"]
  node_authui["Auth context<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_server["Express API<br/>[server.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_auth_controller["Authentication<br/>[auth.controller.js]"]
  node_access["JWT access control<br/>[auth.middleware.js]"]
  node_complaint_routes["Complaint routes"]
end

subgraph group_triage["Complaint lifecycle"]
  node_complaint_controller["Complaint handling"]
  node_nlp["AI classification<br/>[nlpService.js]"]
  node_priority["Priority scoring<br/>[priorityService.js]"]
  node_spam["Duplicate detection"]
  node_escalation["SLA escalation"]
end

subgraph group_civic["Civic operations"]
  node_servant["Officer workflows"]
  node_mayor["Mayor workflows"]
  node_admin["Admin workflows"]
  node_broadcast["Emergency broadcasts"]
  node_reports["Analytics and reports"]
  node_volunteer["Volunteer program"]
end

subgraph group_platform["Persistence and integrations"]
  node_complaints[("Complaint records<br/>[Complaint.model.js]")]
  node_users[("User accounts<br/>[User.model.js]")]
  node_notifications["Notification delivery"]
  node_notification_store[("Notification records")]
  node_email["Email delivery<br/>[emailService.js]"]
end

node_citizens(("Civic users"))
node_mongo[("MongoDB")]
node_ai_provider{{"AI services"}}

node_citizens -->|"use"| node_web
node_web -->|"uses"| node_authui
node_authui -->|"calls"| node_api_client
node_web -.->|"requests"| node_api_client
node_api_client -->|"REST requests"| node_server
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_complaint_routes
node_auth_routes -->|"protects"| node_access
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"reads and writes"| node_users
node_complaint_routes -->|"protects"| node_access
node_complaint_routes -->|"dispatches"| node_complaint_controller
node_complaint_controller -->|"classifies"| node_nlp
node_complaint_controller -->|"scores priority"| node_priority
node_complaint_controller -->|"checks duplicates"| node_spam
node_complaint_controller -->|"reads and writes"| node_complaints
node_complaint_controller -->|"reads and updates"| node_users
node_nlp -.->|"classifies via"| node_ai_provider
node_server -->|"starts job"| node_escalation
node_escalation -->|"scans and updates"| node_complaints
node_servant -->|"manages tickets"| node_complaints
node_mayor -.->|"uses complaint data"| node_complaints
node_admin -->|"reviews accounts"| node_users
node_broadcast -.->|"delivers alerts"| node_notifications
node_reports -->|"reads"| node_complaints
node_volunteer -.->|"serves citizens"| node_users
node_notifications -->|"creates"| node_notification_store
node_notifications -->|"looks up recipients"| node_users
node_notifications -->|"sends email"| node_email
node_complaints -.->|"persisted in"| node_mongo
node_users -.->|"persisted in"| node_mongo

click node_web "https://github.com/ifaz07/shomadhan/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/ifaz07/shomadhan/blob/main/frontend/src/context/AuthContext.jsx"
click node_api_client "https://github.com/ifaz07/shomadhan/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/ifaz07/shomadhan/blob/main/backend/server.js"
click node_auth_routes "https://github.com/ifaz07/shomadhan/blob/main/backend/routes/auth.routes.js"
click node_auth_controller "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/auth.controller.js"
click node_access "https://github.com/ifaz07/shomadhan/blob/main/backend/middleware/auth.middleware.js"
click node_complaint_routes "https://github.com/ifaz07/shomadhan/blob/main/backend/routes/complaint.routes.js"
click node_complaint_controller "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/complaint.controller.js"
click node_nlp "https://github.com/ifaz07/shomadhan/blob/main/backend/services/nlpService.js"
click node_priority "https://github.com/ifaz07/shomadhan/blob/main/backend/services/priorityService.js"
click node_spam "https://github.com/ifaz07/shomadhan/blob/main/backend/services/spamDetectionService.js"
click node_escalation "https://github.com/ifaz07/shomadhan/blob/main/backend/services/escalationService.js"
click node_complaints "https://github.com/ifaz07/shomadhan/blob/main/backend/models/Complaint.model.js"
click node_users "https://github.com/ifaz07/shomadhan/blob/main/backend/models/User.model.js"
click node_servant "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/servant.controller.js"
click node_mayor "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/mayor.controller.js"
click node_admin "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/admin.controller.js"
click node_broadcast "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/emergencyBroadcast.controller.js"
click node_reports "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/report.controller.js"
click node_volunteer "https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/volunteer.controller.js"
click node_notifications "https://github.com/ifaz07/shomadhan/blob/main/backend/services/notificationService.js"
click node_notification_store "https://github.com/ifaz07/shomadhan/blob/main/backend/models/Notification.model.js"
click node_email "https://github.com/ifaz07/shomadhan/blob/main/backend/services/emailService.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_web,node_authui,node_api_client,node_citizens toneBlue
class node_server,node_auth_routes,node_auth_controller,node_access,node_complaint_routes,node_mongo toneAmber
class node_complaint_controller,node_nlp,node_priority,node_spam,node_escalation toneMint
class node_servant,node_mayor,node_admin,node_broadcast,node_reports,node_volunteer toneRose
class node_complaints,node_users,node_notifications,node_notification_store,node_email,node_ai_provider toneIndigo
```

## Components

### Web application

- [React application](https://github.com/ifaz07/shomadhan/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/ifaz07/shomadhan/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/ifaz07/shomadhan/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and access

- [Express API](https://github.com/ifaz07/shomadhan/blob/main/backend/server.js): `backend/server.js`
- [Auth routes](https://github.com/ifaz07/shomadhan/blob/main/backend/routes/auth.routes.js): `backend/routes/auth.routes.js`
- [Authentication](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/auth.controller.js): `backend/controllers/auth.controller.js`
- [JWT access control](https://github.com/ifaz07/shomadhan/blob/main/backend/middleware/auth.middleware.js): `backend/middleware/auth.middleware.js`
- [Complaint routes](https://github.com/ifaz07/shomadhan/blob/main/backend/routes/complaint.routes.js): `backend/routes/complaint.routes.js`

### Complaint lifecycle

- [Complaint handling](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/complaint.controller.js): `backend/controllers/complaint.controller.js`
- [AI classification](https://github.com/ifaz07/shomadhan/blob/main/backend/services/nlpService.js): `backend/services/nlpService.js`
- [Priority scoring](https://github.com/ifaz07/shomadhan/blob/main/backend/services/priorityService.js): `backend/services/priorityService.js`
- [Duplicate detection](https://github.com/ifaz07/shomadhan/blob/main/backend/services/spamDetectionService.js): `backend/services/spamDetectionService.js`
- [SLA escalation](https://github.com/ifaz07/shomadhan/blob/main/backend/services/escalationService.js): `backend/services/escalationService.js`

### Civic operations

- [Officer workflows](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/servant.controller.js): `backend/controllers/servant.controller.js`
- [Mayor workflows](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/mayor.controller.js): `backend/controllers/mayor.controller.js`
- [Admin workflows](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/admin.controller.js): `backend/controllers/admin.controller.js`
- [Emergency broadcasts](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/emergencyBroadcast.controller.js): `backend/controllers/emergencyBroadcast.controller.js`
- [Analytics and reports](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/report.controller.js): `backend/controllers/report.controller.js`
- [Volunteer program](https://github.com/ifaz07/shomadhan/blob/main/backend/controllers/volunteer.controller.js): `backend/controllers/volunteer.controller.js`

### Persistence and integrations

- [Complaint records](https://github.com/ifaz07/shomadhan/blob/main/backend/models/Complaint.model.js): `backend/models/Complaint.model.js`
- [User accounts](https://github.com/ifaz07/shomadhan/blob/main/backend/models/User.model.js): `backend/models/User.model.js`
- [Notification delivery](https://github.com/ifaz07/shomadhan/blob/main/backend/services/notificationService.js): `backend/services/notificationService.js`
- [Notification records](https://github.com/ifaz07/shomadhan/blob/main/backend/models/Notification.model.js): `backend/models/Notification.model.js`
- [Email delivery](https://github.com/ifaz07/shomadhan/blob/main/backend/services/emailService.js): `backend/services/emailService.js`

### Other components

- **Civic users**
- **MongoDB**
- **AI services**

## Connections

- Civic users → React application: use
- React application → Auth context: uses (evidence: `frontend/src/App.jsx`)
- Auth context → API client: calls (evidence: `frontend/src/context/AuthContext.jsx`)
- React application → API client: requests
- API client → Express API: REST requests
- Express API → Auth routes: mounts (evidence: `backend/server.js`)
- Express API → Complaint routes: mounts (evidence: `backend/server.js`)
- Auth routes → JWT access control: protects (evidence: `backend/routes/auth.routes.js`)
- Auth routes → Authentication: dispatches (evidence: `backend/routes/auth.routes.js`)
- Authentication → User accounts: reads and writes (evidence: `backend/controllers/auth.controller.js`)
- Complaint routes → JWT access control: protects (evidence: `backend/routes/complaint.routes.js`)
- Complaint routes → Complaint handling: dispatches (evidence: `backend/routes/complaint.routes.js`)
- Complaint handling → AI classification: classifies (evidence: `backend/controllers/complaint.controller.js`)
- Complaint handling → Priority scoring: scores priority (evidence: `backend/controllers/complaint.controller.js`)
- Complaint handling → Duplicate detection: checks duplicates (evidence: `backend/controllers/complaint.controller.js`)
- Complaint handling → Complaint records: reads and writes (evidence: `backend/controllers/complaint.controller.js`)
- Complaint handling → User accounts: reads and updates (evidence: `backend/controllers/complaint.controller.js`)
- AI classification → AI services: classifies via
- Express API → SLA escalation: starts job (evidence: `backend/server.js`)
- SLA escalation → Complaint records: scans and updates (evidence: `backend/services/escalationService.js`)
- Officer workflows → Complaint records: manages tickets (evidence: `backend/controllers/servant.controller.js`)
- Mayor workflows → Complaint records: uses complaint data
- Admin workflows → User accounts: reviews accounts (evidence: `backend/controllers/admin.controller.js`)
- Emergency broadcasts → Notification delivery: delivers alerts
- Analytics and reports → Complaint records: reads (evidence: `backend/controllers/report.controller.js`)
- Volunteer program → User accounts: serves citizens
- Notification delivery → Notification records: creates (evidence: `backend/services/notificationService.js`)
- Notification delivery → User accounts: looks up recipients (evidence: `backend/services/notificationService.js`)
- Notification delivery → Email delivery: sends email (evidence: `backend/services/notificationService.js`)
- Complaint records → MongoDB: persisted in
- User accounts → MongoDB: persisted in
