# suyogshelke/civic-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/suyogshelke/civic-pulse
- Repository: https://github.com/suyogshelke/civic-pulse

## Overview

Civic-Pulse is a civic-issue reporting and resolution platform with citizen, officer, and administrator portals. The main workflow runs from citizen complaint submission and department routing through officer assignment, status updates, resolution evidence, and citizen feedback; administrators also manage users and departments and review analytics. The frontend can use either the browser mock service or the Node API with MySQL. README capabilities supplement incomplete source excerpts, so links for unsampled frontend pages and API modules are shown only at the documented feature level.

Main entry points: [`frontend/src/App.jsx`](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/App.jsx) (Route application), [`frontend/src/api/client.js`](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/client.js) (HTTP client), [`frontend/src/api/mock/service.js`](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/mock/service.js) (Mock API service), [`frontend/src/api/complaints.js`](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/complaints.js) (Complaint API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend portals"]
  node_app["Route application<br/>[App.jsx]"]
  node_auth["Session and access<br/>[AuthContext.jsx]"]
end

subgraph group_workflow["Complaint workflow"]
  node_citizen_portal["Citizen portal"]
  node_officer_portal["Officer portal"]
end

subgraph group_admin["Administration"]
  node_admin_portal["Admin oversight"]
end

subgraph group_services["API services"]
  node_complaint_api["Complaint API<br/>[complaints.js]"]
  node_feedback_api["Feedback API<br/>[feedback.js]"]
  node_analytics_api["Analytics API<br/>[analytics.js]"]
  node_directory_api["User and department APIs<br/>[users.js]"]
  node_auth_api["Authentication API<br/>[auth.js]"]
  node_api_client["HTTP client<br/>[client.js]"]
  node_mock_service["Mock API service<br/>[service.js]"]
  node_server["Node REST API<br/>[server.js]"]
end

subgraph group_state["Persistence"]
  node_mock_store[("Browser mock store<br/>[db.js]")]
  node_mysql[("MySQL database")]
end

node_citizen(("Citizen"))
node_officer(("Officer"))
node_administrator(("Administrator"))

node_citizen -->|"uses"| node_app
node_officer -->|"uses"| node_app
node_administrator -->|"uses"| node_app
node_app -->|"provides session"| node_auth
node_app -->|"routes citizen"| node_citizen_portal
node_app -->|"routes officer"| node_officer_portal
node_app -->|"routes admin"| node_admin_portal
node_auth -->|"authenticates"| node_auth_api
node_citizen_portal -->|"submits and tracks"| node_complaint_api
node_citizen_portal -->|"rates resolution"| node_feedback_api
node_officer_portal -->|"updates complaints"| node_complaint_api
node_admin_portal -->|"assigns complaints"| node_complaint_api
node_admin_portal -->|"requests reports"| node_analytics_api
node_admin_portal -->|"manages directory"| node_directory_api
node_auth_api -->|"sends requests"| node_api_client
node_complaint_api -->|"sends requests"| node_api_client
node_feedback_api -->|"sends requests"| node_api_client
node_analytics_api -->|"sends requests"| node_api_client
node_directory_api -->|"sends requests"| node_api_client
node_auth_api -.->|"dispatches when enabled"| node_mock_service
node_complaint_api -.->|"dispatches when enabled"| node_mock_service
node_feedback_api -.->|"dispatches when enabled"| node_mock_service
node_analytics_api -.->|"dispatches when enabled"| node_mock_service
node_directory_api -.->|"dispatches when enabled"| node_mock_service
node_api_client -->|"HTTP requests"| node_server
node_mock_service -->|"reads and writes"| node_mock_store
node_server -->|"queries and updates"| node_mysql

click node_app "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/App.jsx"
click node_auth "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/auth/AuthContext.jsx"
click node_citizen_portal "https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/citizen"
click node_officer_portal "https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/officer"
click node_complaint_api "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/complaints.js"
click node_feedback_api "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/feedback.js"
click node_admin_portal "https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/admin"
click node_analytics_api "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/analytics.js"
click node_directory_api "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/users.js"
click node_auth_api "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/auth.js"
click node_api_client "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/client.js"
click node_mock_service "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/mock/service.js"
click node_mock_store "https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/mock/db.js"
click node_server "https://github.com/suyogshelke/civic-pulse/blob/main/backend/server.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_auth toneBlue
class node_citizen_portal,node_officer_portal toneAmber
class node_admin_portal toneMint
class node_complaint_api,node_feedback_api,node_analytics_api,node_directory_api,node_auth_api,node_api_client,node_mock_service,node_server toneRose
class node_mock_store,node_mysql,node_citizen,node_officer,node_administrator toneIndigo
```

## Components

### Frontend portals

- [Route application](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session and access](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/auth/AuthContext.jsx): `frontend/src/auth/AuthContext.jsx`

### Complaint workflow

- [Citizen portal](https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/citizen): `frontend/src/pages/citizen`
- [Officer portal](https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/officer): `frontend/src/pages/officer`

### Administration

- [Admin oversight](https://github.com/suyogshelke/civic-pulse/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`

### API services

- [Complaint API](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/complaints.js): `frontend/src/api/complaints.js`
- [Feedback API](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/feedback.js): `frontend/src/api/feedback.js`
- [Analytics API](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/analytics.js): `frontend/src/api/analytics.js`
- [User and department APIs](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/users.js): `frontend/src/api/users.js`
- [Authentication API](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/auth.js): `frontend/src/api/auth.js`
- [HTTP client](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Mock API service](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/mock/service.js): `frontend/src/api/mock/service.js`
- [Node REST API](https://github.com/suyogshelke/civic-pulse/blob/main/backend/server.js): `backend/server.js`

### Persistence

- [Browser mock store](https://github.com/suyogshelke/civic-pulse/blob/main/frontend/src/api/mock/db.js): `frontend/src/api/mock/db.js`
- **MySQL database**

### Other components

- **Citizen**
- **Officer**
- **Administrator**

## Connections

- Citizen → Route application: uses
- Officer → Route application: uses
- Administrator → Route application: uses
- Route application → Session and access: provides session
- Route application → Citizen portal: routes citizen
- Route application → Officer portal: routes officer
- Route application → Admin oversight: routes admin
- Session and access → Authentication API: authenticates
- Citizen portal → Complaint API: submits and tracks
- Citizen portal → Feedback API: rates resolution
- Officer portal → Complaint API: updates complaints
- Admin oversight → Complaint API: assigns complaints
- Admin oversight → Analytics API: requests reports
- Admin oversight → User and department APIs: manages directory
- Authentication API → HTTP client: sends requests
- Complaint API → HTTP client: sends requests
- Feedback API → HTTP client: sends requests
- Analytics API → HTTP client: sends requests
- User and department APIs → HTTP client: sends requests
- Authentication API → Mock API service: dispatches when enabled
- Complaint API → Mock API service: dispatches when enabled
- Feedback API → Mock API service: dispatches when enabled
- Analytics API → Mock API service: dispatches when enabled
- User and department APIs → Mock API service: dispatches when enabled
- HTTP client → Node REST API: HTTP requests
- Mock API service → Browser mock store: reads and writes
- Node REST API → MySQL database: queries and updates