# prasanna-ks-85/incident-analysis-system architecture

> Architecture diagram of the GitHub repository prasanna-ks-85/incident-analysis-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prasanna-ks-85/incident-analysis-system
- Repository: https://github.com/prasanna-ks-85/incident-analysis-system

## Overview

Civic Sentinel turns citizen grievances into prioritized, geolocated incidents for administrative response. The main path runs from citizen submission through translation, classification, sentiment and urgency analysis, and CCI scoring, then stores the ticket for administrative review. The README also documents voice/image evidence, cluster detection, geospatial visualization and routing, PDF reporting, and resolution emails. Some integrations are documented rather than visible in sampled implementation; those links are marked accordingly.

Main entry points: [`4_pipeline/grievance_pipeline.py`](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/4_pipeline/grievance_pipeline.py) (Grievance Orchestrator), [`citizen_portal.py`](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/citizen_portal.py) (Citizen Portal), [`utils/db_handler.py`](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/db_handler.py) (Grievance Database Handler), [`admin_dashboard.py`](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/admin_dashboard.py) (Admin Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Citizen and Admin Interfaces"]
  node_citizen["Citizen Portal<br/>[citizen_portal.py]"]
  node_mvp["MVP Application<br/>[app.py]"]
  node_mvp_old["Legacy MVP<br/>[app_OLD.py]"]
  node_admin["Admin Dashboard<br/>[admin_dashboard.py]"]
end

subgraph group_analysis["Grievance Analysis"]
  node_pipeline["Grievance Orchestrator"]
  node_translation["Translation Agent<br/>[translator.py]"]
  node_classification["Classification Agent<br/>[classifier.py]"]
  node_sentiment["Sentiment Agent<br/>[sentiment.py]"]
  node_urgency["Urgency Agent<br/>[urgency_detect.py]"]
  node_decision["CCI Decision Agent<br/>[decision.py]"]
end

subgraph group_operations["Incident Operations"]
  node_location["Location Manager"]
  node_clusters["Cluster Detection<br/>[cluster_engine.py]"]
  node_routing["Facility and Route Engine<br/>[route_engine.py]"]
  node_maps["Google Maps Services"]
end

subgraph group_data["Persistence and Reporting"]
  node_database["Grievance Database Handler<br/>[db_handler.py]"]
  node_mongodb[("MongoDB Atlas")]
  node_reports["PDF Report Generator"]
end

node_citizen_actor(("Citizen"))
node_email["Citizen Email Service"]

node_citizen_actor -->|"submits reports"| node_citizen
node_citizen -->|"analyzes complaints"| node_pipeline
node_citizen -->|"gets GPS"| node_location
node_citizen -->|"saves tickets"| node_database
node_pipeline -->|"translates text"| node_translation
node_pipeline -->|"classifies text"| node_classification
node_pipeline -->|"analyzes sentiment"| node_sentiment
node_pipeline -->|"detects urgency"| node_urgency
node_pipeline -->|"computes CCI"| node_decision
node_mvp -->|"analyzes complaints"| node_pipeline
node_mvp -->|"generates PDF"| node_reports
node_mvp_old -->|"analyzes complaints"| node_pipeline
node_admin -->|"fetches tickets"| node_database
node_admin -->|"scans incidents"| node_clusters
node_admin -->|"requests routes"| node_routing
node_routing -->|"queries places and directions"| node_maps
node_clusters -->|"reads tickets; upserts clusters"| node_database
node_database -->|"reads and writes"| node_mongodb
node_citizen -.->|"receives resolution updates"| node_email
node_citizen -.->|"uploads image evidence"| node_citizen

click node_citizen "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/citizen_portal.py"
click node_mvp "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/7_mvp_application/app.py"
click node_mvp_old "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/7_mvp_application/app_OLD.py"
click node_admin "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/admin_dashboard.py"
click node_pipeline "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/4_pipeline/grievance_pipeline.py"
click node_translation "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/translation_agent/translator.py"
click node_classification "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/classification_agent/classifier.py"
click node_sentiment "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/sentiment_agent/sentiment.py"
click node_urgency "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/urgency_agent/urgency_detect.py"
click node_decision "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/decision_agent/decision.py"
click node_location "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/location_manager.py"
click node_clusters "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/cluster_engine.py"
click node_routing "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/route_engine.py"
click node_database "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/db_handler.py"
click node_reports "https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/report_generator.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_citizen,node_mvp,node_mvp_old,node_admin toneBlue
class node_pipeline,node_translation,node_classification,node_sentiment,node_urgency,node_decision toneAmber
class node_location,node_clusters,node_routing,node_maps toneMint
class node_database,node_mongodb,node_reports toneRose
class node_citizen_actor,node_email toneIndigo
```

## Components

### Citizen and Admin Interfaces

- [Citizen Portal](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/citizen_portal.py): `citizen_portal.py`
- [MVP Application](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/7_mvp_application/app.py): `7_mvp_application/app.py`
- [Legacy MVP](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/7_mvp_application/app_OLD.py): `7_mvp_application/app_OLD.py`
- [Admin Dashboard](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/admin_dashboard.py): `admin_dashboard.py`

### Grievance Analysis

- [Grievance Orchestrator](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/4_pipeline/grievance_pipeline.py): `4_pipeline/grievance_pipeline.py`
- [Translation Agent](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/translation_agent/translator.py): `3_agents/translation_agent/translator.py`
- [Classification Agent](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/classification_agent/classifier.py): `3_agents/classification_agent/classifier.py`
- [Sentiment Agent](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/sentiment_agent/sentiment.py): `3_agents/sentiment_agent/sentiment.py`
- [Urgency Agent](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/urgency_agent/urgency_detect.py): `3_agents/urgency_agent/urgency_detect.py`
- [CCI Decision Agent](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/3_agents/decision_agent/decision.py): `3_agents/decision_agent/decision.py`

### Incident Operations

- [Location Manager](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/location_manager.py): `utils/location_manager.py`
- [Cluster Detection](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/cluster_engine.py): `utils/cluster_engine.py`
- [Facility and Route Engine](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/route_engine.py): `utils/route_engine.py`
- **Google Maps Services**

### Persistence and Reporting

- [Grievance Database Handler](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/db_handler.py): `utils/db_handler.py`
- **MongoDB Atlas**
- [PDF Report Generator](https://github.com/prasanna-ks-85/incident-analysis-system/blob/main/utils/report_generator.py): `utils/report_generator.py`

### Other components

- **Citizen**
- **Citizen Email Service**

## Connections

- Citizen → Citizen Portal: submits reports (evidence: `README.md`)
- Citizen Portal → Grievance Orchestrator: analyzes complaints (evidence: `citizen_portal.py`)
- Citizen Portal → Location Manager: gets GPS (evidence: `citizen_portal.py`)
- Citizen Portal → Grievance Database Handler: saves tickets (evidence: `citizen_portal.py`)
- Grievance Orchestrator → Translation Agent: translates text (evidence: `4_pipeline/grievance_pipeline.py`)
- Grievance Orchestrator → Classification Agent: classifies text (evidence: `4_pipeline/grievance_pipeline.py`)
- Grievance Orchestrator → Sentiment Agent: analyzes sentiment (evidence: `4_pipeline/grievance_pipeline.py`)
- Grievance Orchestrator → Urgency Agent: detects urgency (evidence: `4_pipeline/grievance_pipeline.py`)
- Grievance Orchestrator → CCI Decision Agent: computes CCI (evidence: `4_pipeline/grievance_pipeline.py`)
- MVP Application → Grievance Orchestrator: analyzes complaints (evidence: `7_mvp_application/app.py`)
- MVP Application → PDF Report Generator: generates PDF (evidence: `7_mvp_application/app.py`)
- Legacy MVP → Grievance Orchestrator: analyzes complaints (evidence: `7_mvp_application/app_OLD.py`)
- Admin Dashboard → Grievance Database Handler: fetches tickets (evidence: `admin_dashboard.py`)
- Admin Dashboard → Cluster Detection: scans incidents (evidence: `admin_dashboard.py`)
- Admin Dashboard → Facility and Route Engine: requests routes (evidence: `admin_dashboard.py`)
- Facility and Route Engine → Google Maps Services: queries places and directions (evidence: `utils/route_engine.py`)
- Cluster Detection → Grievance Database Handler: reads tickets; upserts clusters (evidence: `utils/cluster_engine.py`)
- Grievance Database Handler → MongoDB Atlas: reads and writes (evidence: `utils/db_handler.py`)
- Citizen Portal → Citizen Email Service: receives resolution updates (evidence: `README.md`)
- Citizen Portal → Citizen Portal: uploads image evidence (evidence: `README.md`)
