# harishb0401/mp-s3 architecture

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

- Interactive diagram: https://gitdiagram.com/harishb0401/mp-s3
- Repository: https://github.com/harishb0401/mp-s3

## Overview

This is a full-stack municipal grievance intake, triage, assignment, and resolution platform. Citizens and municipal staff use role-specific portals to submit or manage cases; the Java HTTP server routes requests to the grievance manager, which coordinates prioritization, duplicate review, department/worker assignment, status tracking, notifications, and reporting over dual-mode persistence. The README documents broader portal capabilities not fully visible in the sampled excerpts; edges for those features cite that documentation rather than implying the unsampled implementation was inspected.

Main entry points: [`backend/src/service/GrievanceManager.java`](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/GrievanceManager.java) (Grievance Orchestrator), [`backend/src/service/Database.java`](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/Database.java) (Persistence Facade), [`backend/src/service/ServerManager.java`](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/ServerManager.java) (HTTP API Server), [`frontend/js/app.js`](https://github.com/harishb0401/mp-s3/blob/main/frontend/js/app.js) (Role Portals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Portals"]
  node_portals["Role Portals<br/>[app.js]"]
  node_api_client["API Client<br/>[api.js]"]
  node_charts["Dashboard Charts<br/>[charts.js]"]
end

subgraph group_api["Backend Operations"]
  node_http["HTTP API Server<br/>[ServerManager.java]"]
  node_manager["Grievance Orchestrator"]
  node_validator["Data Validation<br/>[DataValidator.java]"]
end

subgraph group_domain["Grievance Domain"]
  node_case_model["Complaint Lifecycle<br/>[Complaint.java]"]
  node_priority["Priority Queues"]
  node_duplicates["Duplicate Review"]
  node_location["Location Matching"]
  node_departments["Department Workload<br/>[Department.java]"]
  node_notifications["Role Notifications<br/>[Notification.java]"]
end

subgraph group_persistence["Persistence"]
  node_database_facade["Persistence Facade<br/>[Database.java]"]
  node_repositories["Relational Repositories"]
  node_connection["MySQL Connection"]
  node_json_fallback[("JSON and Memory Store<br/>[Database.java]")]
end

subgraph group_integrity["Identity and Audit"]
  node_identity["User Identity and Roles<br/>[User.java]"]
  node_audit["Status and Audit History"]
end

node_citizens_staff(("Citizens and Staff"))
node_mysql[("MySQL")]

node_citizens_staff -->|"uses"| node_portals
node_portals -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_http
node_http -->|"routes operations"| node_manager
node_http -->|"serves data"| node_database_facade
node_manager -->|"coordinates persistence"| node_database_facade
node_manager -->|"updates cases"| node_case_model
node_manager -->|"queues cases"| node_priority
node_manager -->|"reviews candidates"| node_duplicates
node_manager -->|"matches locations"| node_location
node_manager -->|"assigns workload"| node_departments
node_manager -->|"creates alerts"| node_notifications
node_http -->|"validates input"| node_validator
node_database_facade -->|"uses repositories"| node_repositories
node_repositories -->|"opens connections"| node_connection
node_connection -->|"connects"| node_mysql
node_database_facade -->|"falls back to"| node_json_fallback
node_database_facade -->|"stores accounts"| node_identity
node_repositories -->|"persists transitions"| node_audit
node_portals -->|"renders reports"| node_charts
node_citizens_staff -->|"receives alerts"| node_notifications

click node_portals "https://github.com/harishb0401/mp-s3/blob/main/frontend/js/app.js"
click node_api_client "https://github.com/harishb0401/mp-s3/blob/main/frontend/js/api.js"
click node_charts "https://github.com/harishb0401/mp-s3/blob/main/frontend/js/charts.js"
click node_http "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/ServerManager.java"
click node_manager "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/GrievanceManager.java"
click node_validator "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/DataValidator.java"
click node_case_model "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Complaint.java"
click node_priority "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/DepartmentQueueManager.java"
click node_duplicates "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/DuplicateCandidate.java"
click node_location "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/LocationNormalizer.java"
click node_departments "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Department.java"
click node_notifications "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Notification.java"
click node_database_facade "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/Database.java"
click node_repositories "https://github.com/harishb0401/mp-s3/tree/main/backend/src/repository"
click node_connection "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/DatabaseConnection.java"
click node_json_fallback "https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/Database.java"
click node_identity "https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/User.java"
click node_audit "https://github.com/harishb0401/mp-s3/blob/main/backend/src/repository/StatusUpdateRepository.java"

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_portals,node_api_client,node_charts toneBlue
class node_http,node_manager,node_validator,node_mysql toneAmber
class node_case_model,node_priority,node_duplicates,node_location,node_departments,node_notifications toneMint
class node_database_facade,node_repositories,node_connection,node_json_fallback toneRose
class node_identity,node_audit,node_citizens_staff toneIndigo
```

## Components

### Web Portals

- [Role Portals](https://github.com/harishb0401/mp-s3/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [API Client](https://github.com/harishb0401/mp-s3/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [Dashboard Charts](https://github.com/harishb0401/mp-s3/blob/main/frontend/js/charts.js): `frontend/js/charts.js`

### Backend Operations

- [HTTP API Server](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/ServerManager.java): `backend/src/service/ServerManager.java`
- [Grievance Orchestrator](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/GrievanceManager.java): `backend/src/service/GrievanceManager.java`
- [Data Validation](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/DataValidator.java): `backend/src/service/DataValidator.java`

### Grievance Domain

- [Complaint Lifecycle](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Complaint.java): `backend/src/model/Complaint.java`
- [Priority Queues](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/DepartmentQueueManager.java): `backend/src/model/DepartmentQueueManager.java`
- [Duplicate Review](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/DuplicateCandidate.java): `backend/src/model/DuplicateCandidate.java`
- [Location Matching](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/LocationNormalizer.java): `backend/src/model/LocationNormalizer.java`
- [Department Workload](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Department.java): `backend/src/model/Department.java`
- [Role Notifications](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/Notification.java): `backend/src/model/Notification.java`

### Persistence

- [Persistence Facade](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/Database.java): `backend/src/service/Database.java`
- [Relational Repositories](https://github.com/harishb0401/mp-s3/tree/main/backend/src/repository): `backend/src/repository`
- [MySQL Connection](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/DatabaseConnection.java): `backend/src/service/DatabaseConnection.java`
- [JSON and Memory Store](https://github.com/harishb0401/mp-s3/blob/main/backend/src/service/Database.java): `backend/src/service/Database.java`

### Identity and Audit

- [User Identity and Roles](https://github.com/harishb0401/mp-s3/blob/main/backend/src/model/User.java): `backend/src/model/User.java`
- [Status and Audit History](https://github.com/harishb0401/mp-s3/blob/main/backend/src/repository/StatusUpdateRepository.java): `backend/src/repository/StatusUpdateRepository.java`

### Other components

- **Citizens and Staff**
- **MySQL**

## Connections

- Citizens and Staff → Role Portals: uses (evidence: `README.md`)
- Role Portals → API Client: requests (evidence: `README.md`)
- API Client → HTTP API Server: calls API (evidence: `README.md`)
- HTTP API Server → Grievance Orchestrator: routes operations (evidence: `backend/src/service/ServerManager.java`)
- HTTP API Server → Persistence Facade: serves data (evidence: `backend/src/service/ServerManager.java`)
- Grievance Orchestrator → Persistence Facade: coordinates persistence (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Complaint Lifecycle: updates cases (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Priority Queues: queues cases (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Duplicate Review: reviews candidates (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Location Matching: matches locations (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Department Workload: assigns workload (evidence: `backend/src/service/GrievanceManager.java`)
- Grievance Orchestrator → Role Notifications: creates alerts (evidence: `backend/src/service/GrievanceManager.java`)
- HTTP API Server → Data Validation: validates input (evidence: `backend/src/service/ServerManager.java`)
- Persistence Facade → Relational Repositories: uses repositories (evidence: `backend/src/service/Database.java`)
- Relational Repositories → MySQL Connection: opens connections (evidence: `backend/src/repository/UserRepository.java`)
- MySQL Connection → MySQL: connects (evidence: `backend/src/service/DatabaseConnection.java`)
- Persistence Facade → JSON and Memory Store: falls back to (evidence: `README.md`)
- Persistence Facade → User Identity and Roles: stores accounts (evidence: `backend/src/service/Database.java`)
- Relational Repositories → Status and Audit History: persists transitions (evidence: `backend/src/repository/StatusUpdateRepository.java`)
- Role Portals → Dashboard Charts: renders reports (evidence: `README.md`)
- Citizens and Staff → Role Notifications: receives alerts (evidence: `README.md`)
