# sujith553/civicpulse architecture

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

- Interactive diagram: https://gitdiagram.com/sujith553/civicpulse
- Repository: https://github.com/sujith553/civicpulse

## Overview

CivicPulse is a civic-issue reporting and municipal management platform. Citizens register and verify email, authenticate, submit geotagged reports, and track their issues; administrators review reports, change statuses, and view analytics. The React app routes users to these workflows and calls Spring Boot APIs; backend services enforce business rules and persist user/issue data. The README documents mapping, email, JWT/RBAC, rate limiting, and analytics. Some backend wiring and frontend pages were not sampled, so those links reflect documented capabilities or are omitted where evidence is insufficient.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sujith553/civicpulse/blob/main/frontend/src/App.jsx) (React app routing), [`frontend/src/api/axiosConfig.js`](https://github.com/sujith553/civicpulse/blob/main/frontend/src/api/axiosConfig.js) (HTTP API client), [`backend/src/main/java/com/civicpulse/backend/controller/AuthController.java`](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/AuthController.java) (Authentication endpoints), [`backend/src/main/java/com/civicpulse/backend/service/IssueService.java`](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/IssueService.java) (Issue workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen experience"]
  node_web_app["React app routing<br/>[App.jsx]"]
  node_auth_pages["Sign-in and signup"]
  node_report_page["Report issue<br/>[ReportIssue.jsx]"]
  node_location_map["Location picker"]
  node_issue_views["Issue history and details<br/>[ViewIssues.jsx]"]
  node_profile_page["Citizen profile<br/>[UserProfile.jsx]"]
  node_api_client["HTTP API client<br/>[axiosConfig.js]"]
end

subgraph group_admin["Municipal operations"]
  node_admin_dashboard["Admin analytics<br/>[AdminDashboard.jsx]"]
end

subgraph group_backend["Backend workflows"]
  node_issue_api["Issue endpoints"]
  node_auth_api["Authentication endpoints"]
  node_dashboard_api["Dashboard endpoint"]
  node_issue_service["Issue workflows<br/>[IssueService.java]"]
  node_user_service["Registration and verification<br/>[UserService.java]"]
  node_dto["Request and response models"]
end

subgraph group_security["Identity and security"]
  node_auth_security["JWT and access control<br/>[JwtService.java]"]
  node_rate_filter["Auth rate limiting"]
end

subgraph group_data["Persistence and messaging"]
  node_issue_repo["Issue repository"]
  node_user_repo["User repository"]
  node_domain_entities["User and issue records"]
  node_database[("MySQL database")]
  node_email_service["Email notifications"]
end

node_citizen_actor(("Citizen"))
node_admin_actor(("Administrator"))
node_smtp["SMTP mail service"]
node_nominatim["Nominatim geocoding"]

node_citizen_actor -->|"uses"| node_web_app
node_admin_actor -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_auth_pages
node_web_app -->|"routes to"| node_report_page
node_web_app -->|"routes to"| node_issue_views
node_web_app -->|"guards and routes"| node_admin_dashboard
node_web_app -->|"routes to"| node_profile_page
node_report_page -->|"uses map"| node_location_map
node_report_page -->|"submits reports"| node_api_client
node_issue_views -->|"loads issue data"| node_api_client
node_admin_dashboard -->|"loads analytics"| node_api_client
node_location_map -->|"resolves addresses"| node_nominatim
node_auth_pages -.->|"calls authentication API"| node_api_client
node_api_client -->|"sends API requests"| node_issue_api
node_api_client -->|"sends API requests"| node_auth_api
node_issue_api -->|"delegates issue operations"| node_issue_service
node_auth_api -->|"delegates auth operations"| node_user_service
node_dashboard_api -->|"requests statistics"| node_issue_service
node_issue_service -->|"queries and updates"| node_issue_repo
node_user_service -->|"reads and saves users"| node_user_repo
node_issue_repo -->|"persists issues"| node_domain_entities
node_user_repo -->|"persists users"| node_domain_entities
node_domain_entities -->|"stored in"| node_database
node_issue_service -->|"notifies status changes"| node_email_service
node_user_service -->|"sends verification codes"| node_email_service
node_email_service -->|"dispatches email"| node_smtp
node_rate_filter -->|"limits auth requests"| node_auth_api
node_auth_security -->|"authenticates requests"| node_auth_api
node_issue_api -->|"accepts and returns models"| node_dto
node_auth_api -->|"accepts and returns models"| node_dto

click node_web_app "https://github.com/sujith553/civicpulse/blob/main/frontend/src/App.jsx"
click node_auth_pages "https://github.com/sujith553/civicpulse/tree/main/frontend/src/pages"
click node_report_page "https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/ReportIssue.jsx"
click node_location_map "https://github.com/sujith553/civicpulse/blob/main/frontend/src/components/LocationPickerMap.jsx"
click node_issue_views "https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/ViewIssues.jsx"
click node_profile_page "https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/UserProfile.jsx"
click node_api_client "https://github.com/sujith553/civicpulse/blob/main/frontend/src/api/axiosConfig.js"
click node_admin_dashboard "https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_issue_api "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/IssueController.java"
click node_auth_api "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/AuthController.java"
click node_dashboard_api "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/DashboardController.java"
click node_issue_service "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/IssueService.java"
click node_user_service "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/UserService.java"
click node_dto "https://github.com/sujith553/civicpulse/tree/main/backend/src/main/java/com/civicpulse/backend/dto"
click node_auth_security "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/jwt/JwtService.java"
click node_rate_filter "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/config/RateLimitingFilter.java"
click node_issue_repo "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/repository/IssueRepository.java"
click node_user_repo "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/repository/UserRepository.java"
click node_domain_entities "https://github.com/sujith553/civicpulse/tree/main/backend/src/main/java/com/civicpulse/backend/entity"
click node_email_service "https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/EmailNotificationService.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_web_app,node_auth_pages,node_report_page,node_location_map,node_issue_views,node_profile_page,node_api_client toneBlue
class node_admin_dashboard toneAmber
class node_issue_api,node_auth_api,node_dashboard_api,node_issue_service,node_user_service,node_dto toneMint
class node_auth_security,node_rate_filter toneRose
class node_issue_repo,node_user_repo,node_domain_entities,node_database,node_email_service,node_citizen_actor,node_admin_actor,node_smtp,node_nominatim toneIndigo
```

## Components

### Citizen experience

- [React app routing](https://github.com/sujith553/civicpulse/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in and signup](https://github.com/sujith553/civicpulse/tree/main/frontend/src/pages): `frontend/src/pages`
- [Report issue](https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/ReportIssue.jsx): `frontend/src/pages/ReportIssue.jsx`
- [Location picker](https://github.com/sujith553/civicpulse/blob/main/frontend/src/components/LocationPickerMap.jsx): `frontend/src/components/LocationPickerMap.jsx`
- [Issue history and details](https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/ViewIssues.jsx): `frontend/src/pages/ViewIssues.jsx`
- [Citizen profile](https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/UserProfile.jsx): `frontend/src/pages/UserProfile.jsx`
- [HTTP API client](https://github.com/sujith553/civicpulse/blob/main/frontend/src/api/axiosConfig.js): `frontend/src/api/axiosConfig.js`

### Municipal operations

- [Admin analytics](https://github.com/sujith553/civicpulse/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`

### Backend workflows

- [Issue endpoints](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/IssueController.java): `backend/src/main/java/com/civicpulse/backend/controller/IssueController.java`
- [Authentication endpoints](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/AuthController.java): `backend/src/main/java/com/civicpulse/backend/controller/AuthController.java`
- [Dashboard endpoint](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/controller/DashboardController.java): `backend/src/main/java/com/civicpulse/backend/controller/DashboardController.java`
- [Issue workflows](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/IssueService.java): `backend/src/main/java/com/civicpulse/backend/service/IssueService.java`
- [Registration and verification](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/UserService.java): `backend/src/main/java/com/civicpulse/backend/service/UserService.java`
- [Request and response models](https://github.com/sujith553/civicpulse/tree/main/backend/src/main/java/com/civicpulse/backend/dto): `backend/src/main/java/com/civicpulse/backend/dto`

### Identity and security

- [JWT and access control](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/jwt/JwtService.java): `backend/src/main/java/com/civicpulse/backend/jwt/JwtService.java`
- [Auth rate limiting](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/config/RateLimitingFilter.java): `backend/src/main/java/com/civicpulse/backend/config/RateLimitingFilter.java`

### Persistence and messaging

- [Issue repository](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/repository/IssueRepository.java): `backend/src/main/java/com/civicpulse/backend/repository/IssueRepository.java`
- [User repository](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/repository/UserRepository.java): `backend/src/main/java/com/civicpulse/backend/repository/UserRepository.java`
- [User and issue records](https://github.com/sujith553/civicpulse/tree/main/backend/src/main/java/com/civicpulse/backend/entity): `backend/src/main/java/com/civicpulse/backend/entity`
- **MySQL database**
- [Email notifications](https://github.com/sujith553/civicpulse/blob/main/backend/src/main/java/com/civicpulse/backend/service/EmailNotificationService.java): `backend/src/main/java/com/civicpulse/backend/service/EmailNotificationService.java`

### Other components

- **Citizen**
- **Administrator**
- **SMTP mail service**
- **Nominatim geocoding**

## Connections

- Citizen → React app routing: uses (evidence: `README.md`)
- Administrator → React app routing: uses (evidence: `README.md`)
- React app routing → Sign-in and signup: routes to (evidence: `frontend/src/App.jsx`)
- React app routing → Report issue: routes to (evidence: `frontend/src/App.jsx`)
- React app routing → Issue history and details: routes to (evidence: `frontend/src/App.jsx`)
- React app routing → Admin analytics: guards and routes (evidence: `frontend/src/App.jsx`)
- React app routing → Citizen profile: routes to (evidence: `frontend/src/App.jsx`)
- Report issue → Location picker: uses map (evidence: `frontend/src/pages/ReportIssue.jsx`)
- Report issue → HTTP API client: submits reports (evidence: `frontend/src/pages/ReportIssue.jsx`)
- Issue history and details → HTTP API client: loads issue data (evidence: `frontend/src/pages/ViewIssues.jsx`)
- Admin analytics → HTTP API client: loads analytics (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- Location picker → Nominatim geocoding: resolves addresses (evidence: `README.md`)
- Sign-in and signup → HTTP API client: calls authentication API (evidence: `frontend/src/pages/ViewIssues.jsx`)
- HTTP API client → Issue endpoints: sends API requests (evidence: `README.md`)
- HTTP API client → Authentication endpoints: sends API requests (evidence: `README.md`)
- Issue endpoints → Issue workflows: delegates issue operations (evidence: `backend/src/main/java/com/civicpulse/backend/controller/IssueController.java`)
- Authentication endpoints → Registration and verification: delegates auth operations (evidence: `backend/src/main/java/com/civicpulse/backend/controller/AuthController.java`)
- Dashboard endpoint → Issue workflows: requests statistics (evidence: `backend/src/main/java/com/civicpulse/backend/controller/DashboardController.java`)
- Issue workflows → Issue repository: queries and updates (evidence: `backend/src/main/java/com/civicpulse/backend/service/IssueService.java`)
- Registration and verification → User repository: reads and saves users (evidence: `backend/src/main/java/com/civicpulse/backend/service/UserService.java`)
- Issue repository → User and issue records: persists issues (evidence: `backend/src/main/java/com/civicpulse/backend/repository/IssueRepository.java`)
- User repository → User and issue records: persists users (evidence: `backend/src/main/java/com/civicpulse/backend/repository/UserRepository.java`)
- User and issue records → MySQL database: stored in (evidence: `README.md`)
- Issue workflows → Email notifications: notifies status changes (evidence: `backend/src/main/java/com/civicpulse/backend/service/IssueService.java`)
- Registration and verification → Email notifications: sends verification codes (evidence: `backend/src/main/java/com/civicpulse/backend/service/UserService.java`)
- Email notifications → SMTP mail service: dispatches email (evidence: `README.md`)
- Auth rate limiting → Authentication endpoints: limits auth requests (evidence: `README.md`)
- JWT and access control → Authentication endpoints: authenticates requests (evidence: `README.md`)
- Issue endpoints → Request and response models: accepts and returns models (evidence: `backend/src/main/java/com/civicpulse/backend/controller/IssueController.java`)
- Authentication endpoints → Request and response models: accepts and returns models (evidence: `backend/src/main/java/com/civicpulse/backend/controller/AuthController.java`)
