# bhavnapatel-6/civicpulse-backend architecture

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

- Interactive diagram: https://gitdiagram.com/bhavnapatel-6/civicpulse-backend
- Repository: https://github.com/bhavnapatel-6/civicpulse-backend

## Overview

CivicPulse is a civic-issue reporting and municipal-resolution API. Citizens submit geo-tagged reports, follow their status, and participate through upvotes; authorities review, assign, and resolve complaints, while admins configure categories and SLAs and inspect analytics. The ComplaintService is the central workflow layer; supporting branches include AI validation, priority scoring, SLA monitoring, and reputation/leaderboard features. Several of those branches are documented but their implementation was not sampled, so those links are shown only where README evidence supports them.

Main entry points: [`src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java) (Complaint lifecycle), [`src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java) (Admin API), [`src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java`](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java) (Authentication), [`src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java`](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java) (Complaint API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry points"]
  node_complaint_api["Complaint API"]
  node_authority_api["Authority API"]
  node_admin_api["Admin API"]
  node_auth_api["Auth API"]
  node_leaderboard_api["Leaderboard API"]
end

subgraph group_workflow["Complaint workflow"]
  node_complaint_service["Complaint lifecycle"]
  node_ai_validation["AI validation"]
  node_priority_engine["Priority scoring"]
  node_category_service["Category management"]
end

subgraph group_operations["Civic operations"]
  node_sla_scheduler["SLA monitoring<br/>[SLAScheduler.java]"]
  node_sla_rules["SLA configuration"]
  node_email["Email alerts<br/>[EmailService.java]"]
  node_analytics["Admin analytics<br/>[StatsService.java]"]
  node_reputation["Rewards and badges<br/>[BadgeService.java]"]
end

subgraph group_data["Domain and persistence"]
  node_complaint_data[("Complaint records<br/>[Complaint.java]")]
  node_users[("User records<br/>[User.java]")]
  node_categories[("Categories<br/>[Category.java]")]
  node_complaint_repo["Complaint repository"]
  node_user_repo["User repository"]
end

subgraph group_identity["Identity and access"]
  node_auth_service["Authentication<br/>[AuthService.java]"]
  node_jwt_service["JWT service<br/>[JwtService.java]"]
end

node_citizen(("Citizen"))
node_authority(("Authority"))
node_admin(("Admin"))
node_groq["Groq AI service"]

node_citizen -->|"submits reports"| node_complaint_api
node_authority -->|"reviews reports"| node_authority_api
node_admin -->|"manages platform"| node_admin_api
node_complaint_api -->|"delegates to"| node_complaint_service
node_authority_api -->|"delegates to"| node_complaint_service
node_admin_api -->|"manages categories"| node_category_service
node_admin_api -->|"manages SLA rules"| node_sla_rules
node_admin_api -->|"requests metrics"| node_analytics
node_complaint_service -->|"reads and writes"| node_complaint_repo
node_complaint_service -->|"looks up users"| node_user_repo
node_complaint_service -->|"gets category"| node_category_service
node_complaint_service -->|"validates report"| node_ai_validation
node_complaint_service -->|"scores priority"| node_priority_engine
node_complaint_repo -->|"persists"| node_complaint_data
node_user_repo -->|"persists"| node_users
node_ai_validation -->|"requests validation"| node_groq
node_admin_api -->|"creates authority"| node_auth_service
node_auth_api -.->|"authenticates"| node_auth_service
node_auth_service -->|"issues tokens"| node_jwt_service
node_leaderboard_api -.->|"ranks citizens"| node_users
node_complaint_service -.->|"uses deadlines"| node_sla_rules
node_sla_scheduler -.->|"sends alerts"| node_email
node_complaint_service -.->|"awards activity"| node_reputation

click node_complaint_api "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java"
click node_authority_api "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AuthorityController.java"
click node_admin_api "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java"
click node_auth_api "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AuthController.java"
click node_leaderboard_api "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/LeaderboardController.java"
click node_complaint_service "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java"
click node_ai_validation "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/AIValidationService.java"
click node_priority_engine "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/PriorityEngine.java"
click node_category_service "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/CategoryService.java"
click node_sla_scheduler "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/scheduler/SLAScheduler.java"
click node_sla_rules "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/SLARuleService.java"
click node_email "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/EmailService.java"
click node_analytics "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/StatsService.java"
click node_reputation "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/BadgeService.java"
click node_auth_service "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java"
click node_jwt_service "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/JwtService.java"
click node_complaint_data "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/Complaint.java"
click node_users "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/User.java"
click node_categories "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/Category.java"
click node_complaint_repo "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/repository/ComplaintRepository.java"
click node_user_repo "https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/repository/UserRepository.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_complaint_api,node_authority_api,node_admin_api,node_auth_api,node_leaderboard_api toneBlue
class node_complaint_service,node_ai_validation,node_priority_engine,node_category_service toneAmber
class node_sla_scheduler,node_sla_rules,node_email,node_analytics,node_reputation toneMint
class node_complaint_data,node_users,node_categories,node_complaint_repo,node_user_repo toneRose
class node_auth_service,node_jwt_service,node_citizen,node_authority,node_admin,node_groq toneIndigo
```

## Components

### API entry points

- [Complaint API](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java): `src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java`
- [Authority API](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AuthorityController.java): `src/main/java/com/civicPulse/civicPulse_backend/controller/AuthorityController.java`
- [Admin API](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java): `src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`
- [Auth API](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/AuthController.java): `src/main/java/com/civicPulse/civicPulse_backend/controller/AuthController.java`
- [Leaderboard API](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/controller/LeaderboardController.java): `src/main/java/com/civicPulse/civicPulse_backend/controller/LeaderboardController.java`

### Complaint workflow

- [Complaint lifecycle](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`
- [AI validation](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/AIValidationService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/AIValidationService.java`
- [Priority scoring](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/PriorityEngine.java): `src/main/java/com/civicPulse/civicPulse_backend/service/PriorityEngine.java`
- [Category management](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/CategoryService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/CategoryService.java`

### Civic operations

- [SLA monitoring](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/scheduler/SLAScheduler.java): `src/main/java/com/civicPulse/civicPulse_backend/scheduler/SLAScheduler.java`
- [SLA configuration](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/SLARuleService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/SLARuleService.java`
- [Email alerts](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/EmailService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/EmailService.java`
- [Admin analytics](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/StatsService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/StatsService.java`
- [Rewards and badges](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/BadgeService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/BadgeService.java`

### Domain and persistence

- [Complaint records](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/Complaint.java): `src/main/java/com/civicPulse/civicPulse_backend/entity/Complaint.java`
- [User records](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/User.java): `src/main/java/com/civicPulse/civicPulse_backend/entity/User.java`
- [Categories](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/entity/Category.java): `src/main/java/com/civicPulse/civicPulse_backend/entity/Category.java`
- [Complaint repository](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/repository/ComplaintRepository.java): `src/main/java/com/civicPulse/civicPulse_backend/repository/ComplaintRepository.java`
- [User repository](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/repository/UserRepository.java): `src/main/java/com/civicPulse/civicPulse_backend/repository/UserRepository.java`

### Identity and access

- [Authentication](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java`
- [JWT service](https://github.com/bhavnapatel-6/civicpulse-backend/blob/main/src/main/java/com/civicPulse/civicPulse_backend/service/JwtService.java): `src/main/java/com/civicPulse/civicPulse_backend/service/JwtService.java`

### Other components

- **Citizen**
- **Authority**
- **Admin**
- **Groq AI service**

## Connections

- Citizen → Complaint API: submits reports (evidence: `README.md`)
- Authority → Authority API: reviews reports (evidence: `README.md`)
- Admin → Admin API: manages platform (evidence: `README.md`)
- Complaint API → Complaint lifecycle: delegates to (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/ComplaintController.java`)
- Authority API → Complaint lifecycle: delegates to (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/AuthorityController.java`)
- Admin API → Category management: manages categories (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`)
- Admin API → SLA configuration: manages SLA rules (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`)
- Admin API → Admin analytics: requests metrics (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`)
- Complaint lifecycle → Complaint repository: reads and writes (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`)
- Complaint lifecycle → User repository: looks up users (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`)
- Complaint lifecycle → Category management: gets category (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`)
- Complaint lifecycle → AI validation: validates report (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`)
- Complaint lifecycle → Priority scoring: scores priority (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/ComplaintService.java`)
- Complaint repository → Complaint records: persists (evidence: `src/main/java/com/civicPulse/civicPulse_backend/repository/ComplaintRepository.java`)
- User repository → User records: persists (evidence: `src/main/java/com/civicPulse/civicPulse_backend/repository/UserRepository.java`)
- AI validation → Groq AI service: requests validation (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/AIValidationService.java`)
- Admin API → Authentication: creates authority (evidence: `src/main/java/com/civicPulse/civicPulse_backend/controller/AdminController.java`)
- Auth API → Authentication: authenticates
- Authentication → JWT service: issues tokens (evidence: `src/main/java/com/civicPulse/civicPulse_backend/service/AuthService.java`)
- Leaderboard API → User records: ranks citizens (evidence: `README.md`)
- Complaint lifecycle → SLA configuration: uses deadlines (evidence: `README.md`)
- SLA monitoring → Email alerts: sends alerts (evidence: `README.md`)
- Complaint lifecycle → Rewards and badges: awards activity (evidence: `README.md`)
