# anshul-anuragi/citizen-grievance-redressal-system architecture

> Architecture diagram of the GitHub repository anshul-anuragi/citizen-grievance-redressal-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshul-anuragi/citizen-grievance-redressal-system
- Repository: https://github.com/anshul-anuragi/citizen-grievance-redressal-system

## Overview

JanSeva is a Madhya Pradesh civic grievance portal. Citizens register or submit anonymously, file and track complaints, and communicate through resolution; officers process assigned work while district administrators manage assignment, SLAs, and reopen approvals. The map includes documented analytics, attachments, bilingual UI, and optional AI capabilities. Source excerpts and the index support backend routing and service links; some frontend-to-API and unsampled subsystem links are shown as unverified. The database is the shared state layer.

Main entry points: [`backend/app/main.py`](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/main.py) (API Router and SLA Scanner), [`backend/app/services/complaint_service.py`](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/complaint_service.py) (Complaint Lifecycle), [`backend/app/api/complaints.py`](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/complaints.py) (Complaint API), [`backend/app/services/ai_service.py`](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/ai_service.py) (AI Recommendations and Insights)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Citizen and Staff Portal"]
  node_submission["Submit Grievance<br/>[page.tsx]"]
  node_tracking["Track Complaint<br/>[page.tsx]"]
  node_dashboard["Citizen Dashboard<br/>[page.tsx]"]
  node_detail["Complaint Details<br/>[page.tsx]"]
  node_adminui["District Admin<br/>[page.tsx]"]
  node_officerui["Officer Workspace<br/>[page.tsx]"]
  node_authui["Sign In and Register<br/>[page.tsx]"]
  node_localization["Bilingual UI"]
  node_webapi["Frontend API Client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_authapi["Authentication API<br/>[auth.py]"]
  node_complaintsapi["Complaint API<br/>[complaints.py]"]
  node_adminapi["District Admin API<br/>[district_admin.py]"]
  node_officersapi["Officer API<br/>[officers.py]"]
  node_attachmentsapi["Attachment API<br/>[attachments.py]"]
  node_analyticsapi["Public Analytics API<br/>[analytics.py]"]
  node_aiapi["AI API<br/>[ai.py]"]
  node_notifyapi["Notifications API<br/>[notifications.py]"]
  node_routing["API Router and SLA Scanner<br/>[main.py]"]
end

subgraph group_workflow["Grievance Workflows"]
  node_complaintsvc["Complaint Lifecycle"]
  node_assignment["Officer Assignment"]
  node_notifications["Notification Service"]
  node_ai["AI Recommendations and Insights<br/>[ai_service.py]"]
  node_ai_audit["AI Audit Analysis"]
  node_storage["Attachment Storage<br/>[storage_service.py]"]
end

subgraph group_platform["Identity and State"]
  node_identity["Roles and District Access<br/>[permissions.py]"]
  node_security["Tokens and Security<br/>[security.py]"]
  node_models["Grievance and User Records<br/>[complaint.py]"]
  node_taxonomy["Districts, Categories, SLA Rules<br/>[grievance.py]"]
  node_ai_records["AI Records<br/>[ai.py]"]
  node_database[("Relational Database<br/>[database.py]")]
end

node_citizen(("Citizen"))
node_staff(("District Staff"))
node_gemini["Gemini API"]

node_citizen -->|"submits"| node_submission
node_citizen -->|"tracks"| node_tracking
node_citizen -->|"views"| node_dashboard
node_staff -->|"administers"| node_adminui
node_staff -->|"processes"| node_officerui
node_authui -->|"uses"| node_webapi
node_submission -->|"uses"| node_webapi
node_tracking -->|"uses"| node_webapi
node_submission -->|"uses translations"| node_localization
node_webapi -.->|"sends API requests"| node_routing
node_routing -->|"registers"| node_authapi
node_routing -->|"registers"| node_complaintsapi
node_routing -->|"registers"| node_adminapi
node_routing -->|"registers"| node_officersapi
node_routing -->|"registers"| node_analyticsapi
node_routing -->|"registers"| node_aiapi
node_routing -->|"registers"| node_attachmentsapi
node_routing -->|"registers"| node_notifyapi
node_authapi -->|"checks access"| node_identity
node_authapi -->|"uses tokens"| node_security
node_complaintsapi -->|"delegates lifecycle"| node_complaintsvc
node_complaintsapi -->|"requests notifications"| node_notifications
node_complaintsapi -->|"requests recommendations"| node_ai
node_adminapi -->|"delegates lifecycle"| node_complaintsvc
node_adminapi -->|"requests assignments"| node_assignment
node_adminapi -->|"requests notifications"| node_notifications
node_officersapi -->|"delegates lifecycle"| node_complaintsvc
node_officersapi -->|"requests assignments"| node_assignment
node_officersapi -->|"requests notifications"| node_notifications
node_attachmentsapi -->|"stores files"| node_storage
node_aiapi -->|"requests AI processing"| node_ai
node_routing -->|"scans overdue complaints"| node_complaintsvc
node_complaintsvc -->|"updates lifecycle records"| node_models
node_complaintsvc -->|"reads SLA rules"| node_taxonomy
node_ai -->|"looks up categories"| node_taxonomy
node_ai -->|"writes recommendations"| node_ai_records
node_ai -.->|"optionally requests insights"| node_gemini
node_ai_audit -->|"analyzes complaints"| node_models
node_ai_audit -->|"evaluates AI findings"| node_ai_records
node_storage -.->|"stores file metadata via API"| node_database
node_complaintsapi -->|"reads and writes"| node_database
node_authapi -->|"reads and writes"| node_database
node_database -->|"backs records"| node_models
node_identity -->|"loads user records"| node_database

click node_submission "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/submit/page.tsx"
click node_tracking "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/track/page.tsx"
click node_dashboard "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/dashboard/page.tsx"
click node_detail "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/complaints/%5Bid%5D/page.tsx"
click node_adminui "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/admin/page.tsx"
click node_officerui "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/officer/page.tsx"
click node_authui "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/login/page.tsx"
click node_localization "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/contexts/LanguageContext.tsx"
click node_webapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/services/api.ts"
click node_authapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/auth.py"
click node_complaintsapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/complaints.py"
click node_adminapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/district_admin.py"
click node_officersapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/officers.py"
click node_attachmentsapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/attachments.py"
click node_analyticsapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/analytics.py"
click node_aiapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/ai.py"
click node_notifyapi "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/notifications.py"
click node_routing "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/main.py"
click node_complaintsvc "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/complaint_service.py"
click node_assignment "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/assignment_service.py"
click node_notifications "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/notification_service.py"
click node_ai "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/ai_service.py"
click node_ai_audit "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/ai_audit_service.py"
click node_storage "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/storage_service.py"
click node_identity "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/permissions.py"
click node_security "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/security.py"
click node_models "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/complaint.py"
click node_taxonomy "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/grievance.py"
click node_ai_records "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/ai.py"
click node_database "https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/database.py"

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_submission,node_tracking,node_dashboard,node_detail,node_adminui,node_officerui,node_authui,node_localization,node_webapi toneBlue
class node_authapi,node_complaintsapi,node_adminapi,node_officersapi,node_attachmentsapi,node_analyticsapi,node_aiapi,node_notifyapi,node_routing toneAmber
class node_complaintsvc,node_assignment,node_notifications,node_ai,node_ai_audit,node_storage,node_gemini toneMint
class node_identity,node_security,node_models,node_taxonomy,node_ai_records,node_database toneRose
class node_citizen,node_staff toneIndigo
```

## Components

### Citizen and Staff Portal

- [Submit Grievance](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/submit/page.tsx): `frontend/src/app/submit/page.tsx`
- [Track Complaint](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/track/page.tsx): `frontend/src/app/track/page.tsx`
- [Citizen Dashboard](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/dashboard/page.tsx): `frontend/src/app/dashboard/page.tsx`
- [Complaint Details](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/complaints/%5Bid%5D/page.tsx): `frontend/src/app/complaints/[id]/page.tsx`
- [District Admin](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/admin/page.tsx): `frontend/src/app/admin/page.tsx`
- [Officer Workspace](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/officer/page.tsx): `frontend/src/app/officer/page.tsx`
- [Sign In and Register](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Bilingual UI](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/contexts/LanguageContext.tsx): `frontend/src/contexts/LanguageContext.tsx`
- [Frontend API Client](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend API

- [Authentication API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Complaint API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/complaints.py): `backend/app/api/complaints.py`
- [District Admin API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/district_admin.py): `backend/app/api/district_admin.py`
- [Officer API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/officers.py): `backend/app/api/officers.py`
- [Attachment API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/attachments.py): `backend/app/api/attachments.py`
- [Public Analytics API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [AI API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/ai.py): `backend/app/api/ai.py`
- [Notifications API](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/api/notifications.py): `backend/app/api/notifications.py`
- [API Router and SLA Scanner](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/main.py): `backend/app/main.py`

### Grievance Workflows

- [Complaint Lifecycle](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/complaint_service.py): `backend/app/services/complaint_service.py`
- [Officer Assignment](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/assignment_service.py): `backend/app/services/assignment_service.py`
- [Notification Service](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`
- [AI Recommendations and Insights](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [AI Audit Analysis](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/ai_audit_service.py): `backend/app/services/ai_audit_service.py`
- [Attachment Storage](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`

### Identity and State

- [Roles and District Access](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/permissions.py): `backend/app/core/permissions.py`
- [Tokens and Security](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Grievance and User Records](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/complaint.py): `backend/app/models/complaint.py`
- [Districts, Categories, SLA Rules](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/grievance.py): `backend/app/models/grievance.py`
- [AI Records](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/models/ai.py): `backend/app/models/ai.py`
- [Relational Database](https://github.com/anshul-anuragi/citizen-grievance-redressal-system/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Citizen**
- **District Staff**
- **Gemini API**

## Connections

- Citizen → Submit Grievance: submits (evidence: `README.md`)
- Citizen → Track Complaint: tracks (evidence: `README.md`)
- Citizen → Citizen Dashboard: views (evidence: `README.md`)
- District Staff → District Admin: administers (evidence: `README.md`)
- District Staff → Officer Workspace: processes (evidence: `README.md`)
- Sign In and Register → Frontend API Client: uses
- Submit Grievance → Frontend API Client: uses (evidence: `frontend/src/app/submit/page.tsx`)
- Track Complaint → Frontend API Client: uses (evidence: `frontend/src/app/track/page.tsx`)
- Submit Grievance → Bilingual UI: uses translations
- Frontend API Client → API Router and SLA Scanner: sends API requests
- API Router and SLA Scanner → Authentication API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → Complaint API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → District Admin API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → Officer API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → Public Analytics API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → AI API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → Attachment API: registers (evidence: `backend/app/main.py`)
- API Router and SLA Scanner → Notifications API: registers (evidence: `backend/app/main.py`)
- Authentication API → Roles and District Access: checks access (evidence: `backend/app/api/auth.py`)
- Authentication API → Tokens and Security: uses tokens (evidence: `backend/app/api/auth.py`)
- Complaint API → Complaint Lifecycle: delegates lifecycle (evidence: `backend/app/api/complaints.py`)
- Complaint API → Notification Service: requests notifications (evidence: `backend/app/api/complaints.py`)
- Complaint API → AI Recommendations and Insights: requests recommendations (evidence: `backend/app/api/complaints.py`)
- District Admin API → Complaint Lifecycle: delegates lifecycle (evidence: `backend/app/api/district_admin.py`)
- District Admin API → Officer Assignment: requests assignments (evidence: `backend/app/api/district_admin.py`)
- District Admin API → Notification Service: requests notifications (evidence: `backend/app/api/district_admin.py`)
- Officer API → Complaint Lifecycle: delegates lifecycle (evidence: `backend/app/api/officers.py`)
- Officer API → Officer Assignment: requests assignments (evidence: `backend/app/api/officers.py`)
- Officer API → Notification Service: requests notifications (evidence: `backend/app/api/officers.py`)
- Attachment API → Attachment Storage: stores files (evidence: `backend/app/api/attachments.py`)
- AI API → AI Recommendations and Insights: requests AI processing (evidence: `backend/app/api/ai.py`)
- API Router and SLA Scanner → Complaint Lifecycle: scans overdue complaints (evidence: `backend/app/main.py`)
- Complaint Lifecycle → Grievance and User Records: updates lifecycle records (evidence: `backend/app/services/complaint_service.py`)
- Complaint Lifecycle → Districts, Categories, SLA Rules: reads SLA rules (evidence: `backend/app/services/complaint_service.py`)
- AI Recommendations and Insights → Districts, Categories, SLA Rules: looks up categories (evidence: `backend/app/services/ai_service.py`)
- AI Recommendations and Insights → AI Records: writes recommendations (evidence: `backend/app/services/ai_service.py`)
- AI Recommendations and Insights → Gemini API: optionally requests insights (evidence: `README.md`)
- AI Audit Analysis → Grievance and User Records: analyzes complaints (evidence: `backend/app/services/ai_audit_service.py`)
- AI Audit Analysis → AI Records: evaluates AI findings (evidence: `backend/app/services/ai_audit_service.py`)
- Attachment Storage → Relational Database: stores file metadata via API
- Complaint API → Relational Database: reads and writes (evidence: `backend/app/api/complaints.py`)
- Authentication API → Relational Database: reads and writes (evidence: `backend/app/api/auth.py`)
- Relational Database → Grievance and User Records: backs records (evidence: `backend/app/models/complaint.py`)
- Roles and District Access → Relational Database: loads user records (evidence: `backend/app/core/permissions.py`)