# ishan-debugg/lok-seva-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ishan-debugg/lok-seva-ai
- Repository: https://github.com/ishan-debugg/lok-seva-ai

## Overview

Lok Seva AI is a civic grievance intake, classification, routing, and resolution-tracking platform. Citizens submit complaints through the Streamlit portal; the Node/Express API checks for duplicates, requests department classification from the Flask service, assigns priority and a deadline, then stores the complaint in PostgreSQL. Users can track complaints, while officials manage status and review operational and SLA views. The repository also exposes feedback and language-detection capabilities. The README documents the ML pipeline; unsampled frontend pages are represented by their exact tree paths, with only documented capabilities and sampled wiring linked.

Main entry points: [`frontend/app.py`](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/app.py) (Streamlit Router), [`backend/server.js`](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/server.js) (Express Server), [`backend/controllers/complaintController.js`](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/controllers/complaintController.js) (Complaint Controller), [`ml-service/app.py`](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/app.py) (Prediction API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Citizen and Official Portal"]
  node_streamlit["Streamlit Router<br/>[app.py]"]
  node_home["Portal Home<br/>[home.py]"]
  node_user_portal["Complaint Portal<br/>[user_portal.py]"]
  node_tracking["Complaint Tracking<br/>[track_complaint.py]"]
  node_login["Official Login<br/>[login.py]"]
  node_auth["Session Auth<br/>[auth.py]"]
  node_official_dash["Department Dashboard"]
  node_admin_dash["Admin Dashboard<br/>[admin_dashboard.py]"]
  node_manager_dash["Manager Dashboard"]
  node_sla_dash["SLA Dashboard<br/>[sla_dashboard.py]"]
end

subgraph group_api["Complaint API"]
  node_express["Express Server<br/>[server.js]"]
  node_routes["Complaint Routes<br/>[complaintRoutes.js]"]
  node_controller["Complaint Controller"]
end

subgraph group_ml["Classification Service"]
  node_ml_app["Prediction API<br/>[app.py]"]
  node_preprocess["Text Preprocessing<br/>[preprocess.py]"]
  node_predict["Category Prediction<br/>[predict.py]"]
  node_ml_training["Model Training<br/>[train.py]"]
  node_language["Language Detection<br/>[app.py]"]
end

subgraph group_operations["Persistence and SLA"]
  node_sla["SLA Monitoring<br/>[slaService.js]"]
  node_db_config["Database Client<br/>[db.js]"]
  node_postgres[("PostgreSQL<br/>[schema.sql]")]
  node_uploads["Evidence Uploads"]
end

node_citizen(("Citizen"))
node_official(("Municipal Official"))

node_citizen -->|"opens portal"| node_home
node_home -->|"selects service"| node_streamlit
node_official -->|"signs in"| node_login
node_login -->|"checks credentials"| node_auth
node_streamlit -->|"dispatches page"| node_user_portal
node_streamlit -->|"dispatches page"| node_tracking
node_streamlit -->|"dispatches page"| node_login
node_streamlit -->|"dispatches page"| node_official_dash
node_streamlit -->|"dispatches page"| node_admin_dash
node_streamlit -->|"dispatches page"| node_manager_dash
node_streamlit -->|"dispatches page"| node_sla_dash
node_user_portal -->|"submits complaint"| node_express
node_tracking -->|"requests status"| node_express
node_official_dash -->|"manages complaints"| node_express
node_admin_dash -->|"uses API"| node_express
node_manager_dash -->|"lists and updates"| node_express
node_sla_dash -->|"requests SLA views"| node_express
node_express -->|"mounts routes"| node_routes
node_routes -->|"dispatches requests"| node_controller
node_controller -->|"queries complaints"| node_db_config
node_db_config -->|"reads and writes"| node_postgres
node_controller -->|"requests category"| node_ml_app
node_ml_app -->|"preprocesses text"| node_preprocess
node_ml_app -->|"predicts category"| node_predict
node_express -->|"schedules checks"| node_sla
node_controller -->|"requests SLA data"| node_sla
node_sla -->|"queries and updates"| node_db_config
node_routes -->|"stores evidence"| node_uploads
node_controller -->|"records image path"| node_uploads
node_ml_training -.->|"trains model"| node_predict
node_controller -->|"stores feedback"| node_postgres
node_ml_app -->|"offers language endpoint"| node_language

click node_streamlit "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/app.py"
click node_home "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/home.py"
click node_user_portal "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/user_portal.py"
click node_tracking "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/track_complaint.py"
click node_login "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/login.py"
click node_auth "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/utils/auth.py"
click node_official_dash "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/official_dashboard.py"
click node_admin_dash "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/admin_dashboard.py"
click node_manager_dash "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/manager_dashboard.py"
click node_sla_dash "https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/sla_dashboard.py"
click node_express "https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/server.js"
click node_routes "https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/routes/complaintRoutes.js"
click node_controller "https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/controllers/complaintController.js"
click node_ml_app "https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/app.py"
click node_preprocess "https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/preprocess.py"
click node_predict "https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/predict.py"
click node_sla "https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/services/slaService.js"
click node_db_config "https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/config/db.js"
click node_postgres "https://github.com/ishan-debugg/lok-seva-ai/blob/main/database/schema.sql"
click node_uploads "https://github.com/ishan-debugg/lok-seva-ai/tree/main/backend/uploads"
click node_ml_training "https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/train.py"
click node_language "https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/app.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_streamlit,node_home,node_user_portal,node_tracking,node_login,node_auth,node_official_dash,node_admin_dash,node_manager_dash,node_sla_dash toneBlue
class node_express,node_routes,node_controller toneAmber
class node_ml_app,node_preprocess,node_predict,node_ml_training,node_language toneMint
class node_sla,node_db_config,node_postgres,node_uploads toneRose
class node_citizen,node_official toneIndigo
```

## Components

### Citizen and Official Portal

- [Streamlit Router](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/app.py): `frontend/app.py`
- [Portal Home](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/home.py): `frontend/pages/home.py`
- [Complaint Portal](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/user_portal.py): `frontend/pages/user_portal.py`
- [Complaint Tracking](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/track_complaint.py): `frontend/pages/track_complaint.py`
- [Official Login](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/login.py): `frontend/pages/login.py`
- [Session Auth](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/utils/auth.py): `frontend/utils/auth.py`
- [Department Dashboard](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/official_dashboard.py): `frontend/pages/official_dashboard.py`
- [Admin Dashboard](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/admin_dashboard.py): `frontend/pages/admin_dashboard.py`
- [Manager Dashboard](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/manager_dashboard.py): `frontend/pages/manager_dashboard.py`
- [SLA Dashboard](https://github.com/ishan-debugg/lok-seva-ai/blob/main/frontend/pages/sla_dashboard.py): `frontend/pages/sla_dashboard.py`

### Complaint API

- [Express Server](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/server.js): `backend/server.js`
- [Complaint Routes](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/routes/complaintRoutes.js): `backend/routes/complaintRoutes.js`
- [Complaint Controller](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/controllers/complaintController.js): `backend/controllers/complaintController.js`

### Classification Service

- [Prediction API](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/app.py): `ml-service/app.py`
- [Text Preprocessing](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/preprocess.py): `ml-service/preprocess.py`
- [Category Prediction](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/predict.py): `ml-service/predict.py`
- [Model Training](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/train.py): `ml-service/train.py`
- [Language Detection](https://github.com/ishan-debugg/lok-seva-ai/blob/main/ml-service/app.py): `ml-service/app.py`

### Persistence and SLA

- [SLA Monitoring](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/services/slaService.js): `backend/services/slaService.js`
- [Database Client](https://github.com/ishan-debugg/lok-seva-ai/blob/main/backend/config/db.js): `backend/config/db.js`
- [PostgreSQL](https://github.com/ishan-debugg/lok-seva-ai/blob/main/database/schema.sql): `database/schema.sql`
- [Evidence Uploads](https://github.com/ishan-debugg/lok-seva-ai/tree/main/backend/uploads): `backend/uploads`

### Other components

- **Citizen**
- **Municipal Official**

## Connections

- Citizen → Portal Home: opens portal
- Portal Home → Streamlit Router: selects service
- Municipal Official → Official Login: signs in
- Official Login → Session Auth: checks credentials
- Streamlit Router → Complaint Portal: dispatches page
- Streamlit Router → Complaint Tracking: dispatches page
- Streamlit Router → Official Login: dispatches page
- Streamlit Router → Department Dashboard: dispatches page
- Streamlit Router → Admin Dashboard: dispatches page
- Streamlit Router → Manager Dashboard: dispatches page
- Streamlit Router → SLA Dashboard: dispatches page
- Complaint Portal → Express Server: submits complaint
- Complaint Tracking → Express Server: requests status
- Department Dashboard → Express Server: manages complaints
- Admin Dashboard → Express Server: uses API
- Manager Dashboard → Express Server: lists and updates
- SLA Dashboard → Express Server: requests SLA views
- Express Server → Complaint Routes: mounts routes
- Complaint Routes → Complaint Controller: dispatches requests
- Complaint Controller → Database Client: queries complaints
- Database Client → PostgreSQL: reads and writes
- Complaint Controller → Prediction API: requests category
- Prediction API → Text Preprocessing: preprocesses text
- Prediction API → Category Prediction: predicts category
- Express Server → SLA Monitoring: schedules checks
- Complaint Controller → SLA Monitoring: requests SLA data
- SLA Monitoring → Database Client: queries and updates
- Complaint Routes → Evidence Uploads: stores evidence
- Complaint Controller → Evidence Uploads: records image path
- Model Training → Category Prediction: trains model
- Complaint Controller → PostgreSQL: stores feedback
- Prediction API → Language Detection: offers language endpoint