# vaibhavdsonawane/citypulse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhavdsonawane/citypulse-ai
- Repository: https://github.com/vaibhavdsonawane/citypulse-ai

## Overview

CityPulse AI is a civic-issue reporting and municipal response platform. Citizens register, submit a geolocated complaint with optional photos and text, and follow its status; AI services analyze the report before it enters administrative review and department assignment. Administrators review predictions, dispatch work, and advance complaint status, while public and administrative views surface impact and geographic hotspots. The source excerpts show the main Flask routes, prediction services, and relational models; forecast and some interface capabilities are documented or indexed but not fully sampled.

Main entry points: [`app/routes/admin_routes.py`](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/admin_routes.py) (Admin command center), [`app/routes/citizen_routes.py`](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/citizen_routes.py) (Citizen portal), [`app/models.py`](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/models.py) (Complaint and workflow models), [`app/__init__.py`](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/__init__.py) (Flask application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and portals"]
  node_app["Flask application<br/>[__init__.py]"]
  node_auth["Authentication<br/>[auth_routes.py]"]
  node_web_ui["Portal and map UI"]
end

subgraph group_reporting["Complaint intake and AI"]
  node_citizen_routes["Citizen portal<br/>[citizen_routes.py]"]
  node_vision["Photo verification<br/>[cv_service.py]"]
  node_nlp["Text priority engine<br/>[nlp_service.py]"]
  node_severity["Severity prediction<br/>[ml_service.py]"]
end

subgraph group_operations["Municipal operations"]
  node_admin_routes["Admin command center<br/>[admin_routes.py]"]
  node_public_routes["Public impact views<br/>[main_routes.py]"]
  node_dispatch_ui["AJAX dispatch controls<br/>[main.js]"]
  node_hotspots["Hotspot clustering<br/>[hotspot_service.py]"]
  node_forecast["Complaint forecasting"]
end

subgraph group_data["Application data"]
  node_models["Complaint and workflow models<br/>[models.py]"]
  node_database[("SQLite database<br/>[citypulse.db]")]
end

node_citizen(("Citizen"))
node_admin(("Administrator"))

node_citizen -->|"registers or signs in"| node_auth
node_admin -->|"signs in"| node_auth
node_app -->|"registers route"| node_auth
node_app -->|"registers route"| node_citizen_routes
node_app -->|"registers route"| node_admin_routes
node_app -->|"registers route"| node_public_routes
node_citizen -->|"reports and tracks"| node_citizen_routes
node_admin -->|"reviews and dispatches"| node_admin_routes
node_citizen_routes -->|"analyzes photos"| node_vision
node_citizen_routes -->|"scores descriptions"| node_nlp
node_citizen_routes -->|"predicts severity"| node_severity
node_citizen_routes -->|"records reports"| node_models
node_admin_routes -->|"updates workflow"| node_models
node_admin_routes -->|"requests forecast"| node_forecast
node_admin_routes -->|"requests clusters"| node_hotspots
node_public_routes -->|"queries city data"| node_models
node_public_routes -->|"analyzes complaints"| node_hotspots
node_auth -->|"looks up users"| node_models
node_models -->|"persists records"| node_database
node_citizen_routes -.->|"serves portal views"| node_web_ui
node_admin_routes -.->|"serves admin views"| node_web_ui
node_dispatch_ui -.->|"sends AJAX dispatch"| node_admin_routes
node_admin_routes -.->|"shows GIS and review queue"| node_admin

click node_app "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/__init__.py"
click node_auth "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/auth_routes.py"
click node_citizen_routes "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/citizen_routes.py"
click node_admin_routes "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/admin_routes.py"
click node_public_routes "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/main_routes.py"
click node_web_ui "https://github.com/vaibhavdsonawane/citypulse-ai/tree/main/app/templates"
click node_dispatch_ui "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/static/js/main.js"
click node_vision "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/cv_service.py"
click node_nlp "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/nlp_service.py"
click node_severity "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/ml_service.py"
click node_hotspots "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/hotspot_service.py"
click node_forecast "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/forecast_service.py"
click node_models "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/models.py"
click node_database "https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/citypulse.db"

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_app,node_auth,node_web_ui toneBlue
class node_citizen_routes,node_vision,node_nlp,node_severity toneAmber
class node_admin_routes,node_public_routes,node_dispatch_ui,node_hotspots,node_forecast toneMint
class node_models,node_database toneRose
class node_citizen,node_admin toneIndigo
```

## Components

### Access and portals

- [Flask application](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/__init__.py): `app/__init__.py`
- [Authentication](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/auth_routes.py): `app/routes/auth_routes.py`
- [Portal and map UI](https://github.com/vaibhavdsonawane/citypulse-ai/tree/main/app/templates): `app/templates`

### Complaint intake and AI

- [Citizen portal](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/citizen_routes.py): `app/routes/citizen_routes.py`
- [Photo verification](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/cv_service.py): `app/controllers/cv_service.py`
- [Text priority engine](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/nlp_service.py): `app/controllers/nlp_service.py`
- [Severity prediction](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/ml_service.py): `app/controllers/ml_service.py`

### Municipal operations

- [Admin command center](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/admin_routes.py): `app/routes/admin_routes.py`
- [Public impact views](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/routes/main_routes.py): `app/routes/main_routes.py`
- [AJAX dispatch controls](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/static/js/main.js): `app/static/js/main.js`
- [Hotspot clustering](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/hotspot_service.py): `app/controllers/hotspot_service.py`
- [Complaint forecasting](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/controllers/forecast_service.py): `app/controllers/forecast_service.py`

### Application data

- [Complaint and workflow models](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/app/models.py): `app/models.py`
- [SQLite database](https://github.com/vaibhavdsonawane/citypulse-ai/blob/main/citypulse.db): `citypulse.db`

### Other components

- **Citizen**
- **Administrator**

## Connections

- Citizen → Authentication: registers or signs in (evidence: `app/routes/auth_routes.py`)
- Administrator → Authentication: signs in (evidence: `app/routes/auth_routes.py`)
- Flask application → Authentication: registers route (evidence: `app/__init__.py`)
- Flask application → Citizen portal: registers route (evidence: `app/__init__.py`)
- Flask application → Admin command center: registers route (evidence: `app/__init__.py`)
- Flask application → Public impact views: registers route (evidence: `app/__init__.py`)
- Citizen → Citizen portal: reports and tracks (evidence: `README.md`)
- Administrator → Admin command center: reviews and dispatches (evidence: `README.md`)
- Citizen portal → Photo verification: analyzes photos (evidence: `app/routes/citizen_routes.py`)
- Citizen portal → Text priority engine: scores descriptions (evidence: `app/routes/citizen_routes.py`)
- Citizen portal → Severity prediction: predicts severity (evidence: `app/routes/citizen_routes.py`)
- Citizen portal → Complaint and workflow models: records reports (evidence: `app/routes/citizen_routes.py`)
- Admin command center → Complaint and workflow models: updates workflow (evidence: `app/routes/admin_routes.py`)
- Admin command center → Complaint forecasting: requests forecast (evidence: `app/routes/admin_routes.py`)
- Admin command center → Hotspot clustering: requests clusters (evidence: `app/routes/admin_routes.py`)
- Public impact views → Complaint and workflow models: queries city data (evidence: `app/routes/main_routes.py`)
- Public impact views → Hotspot clustering: analyzes complaints (evidence: `app/routes/main_routes.py`)
- Authentication → Complaint and workflow models: looks up users (evidence: `app/routes/auth_routes.py`)
- Complaint and workflow models → SQLite database: persists records (evidence: `app/models.py`)
- Citizen portal → Portal and map UI: serves portal views (evidence: `README.md`)
- Admin command center → Portal and map UI: serves admin views (evidence: `README.md`)
- AJAX dispatch controls → Admin command center: sends AJAX dispatch (evidence: `README.md`)
- Admin command center → Administrator: shows GIS and review queue (evidence: `README.md`)
