# rithik-dev31/civicpulse_ai architecture

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

- Interactive diagram: https://gitdiagram.com/rithik-dev31/civicpulse_ai
- Repository: https://github.com/rithik-dev31/civicpulse_ai

## Overview

CivicPulse AI is a Django civic-complaint portal. Citizens submit location-tagged reports with optional photos; the application checks photos, classifies the issue, and looks for nearby text-similar reports before creating or linking a report. Department staff manage complaint status and history, while staff-facing administration supports account and complaint management. The excerpts substantiate the intake and department workflow; README is empty, and unsampled admin and analytics behavior is represented only where the tree supports it. The configured database and deployment details were not inspected.

Main entry points: [`complaints/views.py`](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/views.py) (Portal workflows), [`department/views.py`](https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/views.py) (Staff workflow), [`complaints/models.py`](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/models.py) (Complaint records), [`complaints/forms.py`](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/forms.py) (Report form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Citizen intake"]
  node_intake_views["Portal workflows<br/>[views.py]"]
  node_submission_form["Report form<br/>[forms.py]"]
end

subgraph group_analysis["Report analysis"]
  node_classifier["Issue classifier<br/>[classifier.py]"]
  node_photo_check["Photo verification"]
  node_duplicate_check["Duplicate matching"]
  node_priority["Priority scoring<br/>[priority.py]"]
end

subgraph group_records["Complaint records"]
  node_complaint_records[("Complaint records<br/>[models.py]")]
  node_report_records[("Citizen reports<br/>[models.py]")]
  node_staff_records[("Department staff<br/>[models.py]")]
end

subgraph group_operations["Department operations"]
  node_department_views["Staff workflow<br/>[views.py]"]
  node_status_history[("Status history<br/>[models.py]")]
end

subgraph group_administration["Administration"]
  node_staff_admin["Staff administration<br/>[views.py]"]
  node_admin_complaints["Complaint oversight<br/>[complaints.html]"]
  node_admin_analytics["Analytics dashboard<br/>[analytics.html]"]
end

node_citizen(("Citizen"))
node_department_user(("Department staff"))

node_citizen -->|"submits reports"| node_intake_views
node_intake_views -->|"validates with"| node_submission_form
node_intake_views -->|"verifies photos"| node_photo_check
node_intake_views -->|"checks duplicates"| node_duplicate_check
node_intake_views -->|"classifies issue"| node_classifier
node_intake_views -->|"sets priority"| node_priority
node_intake_views -->|"creates or updates"| node_complaint_records
node_intake_views -->|"links reporter"| node_report_records
node_duplicate_check -->|"uses text similarity"| node_photo_check
node_classifier -->|"uses categories"| node_complaint_records
node_submission_form -->|"uses department choices"| node_staff_records
node_department_user -->|"updates complaints"| node_department_views
node_department_views -->|"reads and updates"| node_complaint_records
node_department_views -->|"uses priority logic"| node_priority
node_department_views -->|"records status changes"| node_status_history
node_status_history -->|"references complaint"| node_complaint_records
node_staff_admin -->|"creates staff accounts"| node_staff_records

click node_intake_views "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/views.py"
click node_submission_form "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/forms.py"
click node_classifier "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/classifier.py"
click node_photo_check "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/image_verification.py"
click node_duplicate_check "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/duplicate_detection.py"
click node_priority "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/priority.py"
click node_complaint_records "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/models.py"
click node_report_records "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/models.py"
click node_staff_records "https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/models.py"
click node_department_views "https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/views.py"
click node_status_history "https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/models.py"
click node_staff_admin "https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/views.py"
click node_admin_complaints "https://github.com/rithik-dev31/civicpulse_ai/blob/main/templates/admin/complaints.html"
click node_admin_analytics "https://github.com/rithik-dev31/civicpulse_ai/blob/main/templates/admin/analytics.html"

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_intake_views,node_submission_form toneBlue
class node_classifier,node_photo_check,node_duplicate_check,node_priority toneAmber
class node_complaint_records,node_report_records,node_staff_records toneMint
class node_department_views,node_status_history toneRose
class node_staff_admin,node_admin_complaints,node_admin_analytics,node_citizen,node_department_user toneIndigo
```

## Components

### Citizen intake

- [Portal workflows](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/views.py): `complaints/views.py`
- [Report form](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/forms.py): `complaints/forms.py`

### Report analysis

- [Issue classifier](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/classifier.py): `complaints/classifier.py`
- [Photo verification](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/image_verification.py): `complaints/image_verification.py`
- [Duplicate matching](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/duplicate_detection.py): `complaints/duplicate_detection.py`
- [Priority scoring](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/priority.py): `complaints/priority.py`

### Complaint records

- [Complaint records](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/models.py): `complaints/models.py`
- [Citizen reports](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/models.py): `complaints/models.py`
- [Department staff](https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/models.py): `department/models.py`

### Department operations

- [Staff workflow](https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/views.py): `department/views.py`
- [Status history](https://github.com/rithik-dev31/civicpulse_ai/blob/main/department/models.py): `department/models.py`

### Administration

- [Staff administration](https://github.com/rithik-dev31/civicpulse_ai/blob/main/complaints/views.py): `complaints/views.py`
- [Complaint oversight](https://github.com/rithik-dev31/civicpulse_ai/blob/main/templates/admin/complaints.html): `templates/admin/complaints.html`
- [Analytics dashboard](https://github.com/rithik-dev31/civicpulse_ai/blob/main/templates/admin/analytics.html): `templates/admin/analytics.html`

### Other components

- **Citizen**
- **Department staff**

## Connections

- Citizen → Portal workflows: submits reports (evidence: `complaints/views.py`)
- Portal workflows → Report form: validates with (evidence: `complaints/views.py`)
- Portal workflows → Photo verification: verifies photos (evidence: `complaints/views.py`)
- Portal workflows → Duplicate matching: checks duplicates (evidence: `complaints/views.py`)
- Portal workflows → Issue classifier: classifies issue (evidence: `complaints/views.py`)
- Portal workflows → Priority scoring: sets priority (evidence: `complaints/views.py`)
- Portal workflows → Complaint records: creates or updates (evidence: `complaints/views.py`)
- Portal workflows → Citizen reports: links reporter (evidence: `complaints/views.py`)
- Duplicate matching → Photo verification: uses text similarity (evidence: `complaints/duplicate_detection.py`)
- Issue classifier → Complaint records: uses categories (evidence: `complaints/classifier.py`)
- Report form → Department staff: uses department choices (evidence: `complaints/forms.py`)
- Department staff → Staff workflow: updates complaints (evidence: `department/views.py`)
- Staff workflow → Complaint records: reads and updates (evidence: `department/views.py`)
- Staff workflow → Priority scoring: uses priority logic (evidence: `department/views.py`)
- Staff workflow → Status history: records status changes (evidence: `department/views.py`)
- Status history → Complaint records: references complaint (evidence: `department/models.py`)
- Staff administration → Department staff: creates staff accounts