# aaditya02123/nagarsetu architecture

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

- Interactive diagram: https://gitdiagram.com/aaditya02123/nagarsetu
- Repository: https://github.com/aaditya02123/nagarsetu

## Overview

1. **Overall shape**
   - NagarSetu is a three-part system: a **React frontend**, a **FastAPI backend**, and a **separate ML inference service**.  
   - The backend is the main application boundary: it handles authentication, complaint persistence, admin operations, and orchestration of ML predictions.

2. **Frontend subsystem**
   - `NagarSetu-Frontend` is a Vite-based React app organized around user-facing pages (`Home`, `Login`, `Register`, `Report`, `UserDashboard`) and a separate admin area under `src/pages/admin`.
   - `src/Api.js` is the client-side API boundary to the backend.
   - `ProtectedRoute.jsx` indicates route guarding for authenticated and role-based access, especially for admin pages.

3. **Backend application structure**
   - `NagarSetu-Backend/app` is organized in a typical FastAPI layered layout:
     - `core` for configuration, database wiring, and security
     - `models` for SQLAlchemy entities
     - `schemas` for Pydantic request/response contracts
     - `routers` for HTTP endpoints
     - `services` for business logic
     - `middleware` for request-level auth enforcement
   - `main.py` is the backend entrypoint.

4. **Backend API boundaries**
   - The routers split responsibilities:
     - `auth.py` for registration/login and token handling
     - `complaints.py` for citizen complaint submission and complaint retrieval
     - `admin.py` for admin-only complaint management and analytics-style access
   - This separation suggests a clean API surface where frontend pages map to distinct backend resources.

5. **Authentication and access control**
   - Security is JWT-based, with password hashing handled in `core/security.py`.
   - `middleware/auth.py` implies request interception or dependency-based protection for privileged routes.
   - The architecture supports at least two roles: **citizen** and **admin**, with admin functions isolated behind protected endpoints and UI routes.

6. **Complaint domain model**
   - The main business object is the **complaint**, represented in both database models and API schemas (`models/complaint.py`, `schemas/complaint.py`).
   - Complaints include user-submitted metadata such as title, description, category, location/city, image upload, status, department assignment, and likely AI-derived fields such as severity/priority.

7. **Citizen complaint flow**
   - A citizen submits a report from the frontend, which sends data to the backend complaint endpoints.
   - The backend stores complaint data in PostgreSQL, saves uploaded media under `uploads/`, and forwards the image to the ML inference layer for classification.
   - The result comes back as issue category, confidence, severity, and suggested department, which are then persisted with the complaint record.

8. **Admin complaint management flow**
   - Admin pages consume backend endpoints that expose the full complaint set and operational actions.
   - Admins can update status, reassign departments, inspect citizen details, review complaint images, and track resolution progress.
   - The admin dashboard also consumes aggregate data for overview cards, analytics, and departmental performance.

9. **Machine learning boundary**
   - ML is not embedded directly into the frontend; it is a distinct inference subsystem.
   - `NagarSetu-Backend/inference_api.py` serves as the runtime inference API, while `NagarSetu-ML/` contains the training/evaluation/export pipeline.
   - The model artifacts live in `ml_models/` and `models/`, including ONNX and PyTorch exports plus class labels, which indicates the deployed inference path is optimized for serving rather than training.

10. **Data storage and persistence**
   - PostgreSQL is the primary transactional store, accessed through SQLAlchemy and initialized via Alembic configuration (`alembic.ini`).
   - `seed.py` suggests initial bootstrap data for users, admins, or reference records.
   - Complaint images are stored on disk in an `uploads/` hierarchy, so the system has both relational data and file-based media storage.

11. **Configuration and environment**
   - Backend runtime configuration comes from `.env`, including database URL, JWT secret, token expiry, and frontend origin.
   - The frontend also has its own `.env`, indicating the UI is configured separately from the API.
   - This implies a decoupled deployment model where frontend, backend, and ML service can be started and scaled independently.

12. **Training vs serving split**
   - `NagarSetu-ML` is the offline ML development environment: dataset download/organization, training, evaluation, export, and dataset verification scripts live there.
   - The backend repository then consumes the exported model for production inference, which is a clear boundary between model development and application runtime.

13. **Operational flow summary**
   - Browser → React app → FastAPI backend → PostgreSQL and uploads storage → ML inference API/model artifacts → backend persists enriched complaint → admin dashboard consumes the updated complaint state.
   - That is the core architecture to capture in a diagram: **presentation layer, application/API layer, ML service layer, and persistence layer**.

Main entry points: [`NagarSetu-Backend/app/services/complaint_service.py`](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/services/complaint_service.py) (Complaint service), [`NagarSetu-Backend/main.py`](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/main.py) (API app), [`NagarSetu-Backend/app/routers`](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/routers) (Routers), [`NagarSetu-Backend/app/routers/auth.py`](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/auth.py) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>Vite/React UI<br/>[App.jsx]"]
  node_frontend_api["API client<br/>HTTP client<br/>[Api.js]"]
  node_frontend_protected{{"Route guard<br/>auth gate<br/>[ProtectedRoute.jsx]"}}
  node_frontend_pages["Citizen pages<br/>route pages"]
  node_frontend_admin["Admin UI<br/>admin pages"]
end

subgraph group_backend["Backend"]
  node_backend_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_core["Core<br/>config/db/security"]
  node_backend_middleware{{"Auth middleware<br/>request guard<br/>[auth.py]"}}
  node_backend_routers["Routers<br/>HTTP API"]
  node_backend_auth_router["Auth API<br/>router<br/>[auth.py]"]
  node_backend_complaint_router["Complaint API<br/>router<br/>[complaints.py]"]
  node_backend_admin_router["Admin API<br/>router<br/>[admin.py]"]
  node_backend_service["Complaint service<br/>business logic"]
  node_backend_models["Models<br/>ORM entities"]
  node_backend_schemas["Schemas<br/>Pydantic contracts"]
  node_backend_inference["Inference API<br/>ML serving<br/>[inference_api.py]"]
end

subgraph group_ml["ML"]
  node_ml_pipeline["ML pipeline<br/>training/export<br/>[train.py]"]
  node_ml_artifacts[("Model artifacts<br/>exported model<br/>[nagarsetu.onnx]")]
end

subgraph group_data["Data"]
  node_db_store[("PostgreSQL<br/>relational store<br/>[database.py]")]
  node_upload_store["Uploads<br/>file store"]
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"uses"| node_frontend_protected
node_frontend_pages -->|"rendered by"| node_frontend_app
node_frontend_admin -->|"protected by"| node_frontend_protected
node_frontend_api -->|"HTTP"| node_backend_main
node_backend_main -->|"mounts"| node_backend_routers
node_backend_main -->|"initializes"| node_backend_core
node_backend_main -->|"applies"| node_backend_middleware
node_backend_routers -->|"includes"| node_backend_auth_router
node_backend_routers -->|"includes"| node_backend_complaint_router
node_backend_routers -->|"includes"| node_backend_admin_router
node_backend_auth_router -->|"uses"| node_backend_core
node_backend_auth_router -->|"validates"| node_backend_schemas
node_backend_complaint_router -->|"delegates"| node_backend_service
node_backend_service -->|"persists"| node_backend_models
node_backend_service -->|"maps"| node_backend_schemas
node_backend_service -->|"predicts"| node_backend_inference
node_backend_inference -->|"loads"| node_ml_artifacts
node_backend_service -->|"reads/writes"| node_db_store
node_backend_service -->|"stores"| node_upload_store
node_ml_pipeline -->|"produces"| node_ml_artifacts

click node_frontend_app "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/App.jsx"
click node_frontend_api "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/Api.js"
click node_frontend_protected "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/components/ProtectedRoute.jsx"
click node_frontend_pages "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Frontend/src/pages"
click node_frontend_admin "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Frontend/src/pages/admin"
click node_backend_main "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/main.py"
click node_backend_core "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/core"
click node_backend_middleware "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/middleware/auth.py"
click node_backend_routers "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/routers"
click node_backend_auth_router "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/auth.py"
click node_backend_complaint_router "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/complaints.py"
click node_backend_admin_router "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/admin.py"
click node_backend_service "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/services/complaint_service.py"
click node_backend_models "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/models"
click node_backend_schemas "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/schemas"
click node_backend_inference "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/inference_api.py"
click node_ml_pipeline "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-ML/train.py"
click node_ml_artifacts "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/ml_models/nagarsetu.onnx"
click node_db_store "https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/core/database.py"
click node_upload_store "https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/uploads"

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_frontend_app,node_frontend_api,node_frontend_protected,node_frontend_pages,node_frontend_admin toneBlue
class node_backend_main,node_backend_core,node_backend_middleware,node_backend_routers,node_backend_auth_router,node_backend_complaint_router,node_backend_admin_router,node_backend_service,node_backend_models,node_backend_schemas,node_backend_inference toneAmber
class node_ml_pipeline,node_ml_artifacts toneMint
class node_db_store,node_upload_store toneRose
```

## Components

### Frontend

React Vite UI and client-side routing

- [React app](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/App.jsx): Vite/React UI · Browser-facing presentation layer and routed pages · `NagarSetu-Frontend/src/App.jsx`
- [API client](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/Api.js): HTTP client · Frontend boundary for backend requests · `NagarSetu-Frontend/src/Api.js`
- [Route guard](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Frontend/src/components/ProtectedRoute.jsx): auth gate · Protects authenticated and role-based routes · `NagarSetu-Frontend/src/components/ProtectedRoute.jsx`
- [Citizen pages](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Frontend/src/pages): route pages · Home, login, register, report, dashboard, and about screens · `NagarSetu-Frontend/src/pages`
- [Admin UI](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Frontend/src/pages/admin): admin pages · Admin dashboard, complaints, analytics, departments, and settings · `NagarSetu-Frontend/src/pages/admin`

### Backend

FastAPI application and domain services

- [API app](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/main.py): FastAPI entrypoint · Backend application bootstrap and router assembly · `NagarSetu-Backend/main.py`
- [Core](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/core): config/db/security · Configuration, database wiring, and password/JWT security · `NagarSetu-Backend/app/core`
- [Auth middleware](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/middleware/auth.py): request guard · Request-level protection for privileged backend routes · `NagarSetu-Backend/app/middleware/auth.py`
- [Routers](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/routers): HTTP API · Public and admin endpoint surfaces · `NagarSetu-Backend/app/routers`
- [Auth API](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/auth.py): router · Registration, login, and token handling · `NagarSetu-Backend/app/routers/auth.py`
- [Complaint API](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/complaints.py): router · Complaint submission and retrieval endpoints · `NagarSetu-Backend/app/routers/complaints.py`
- [Admin API](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/routers/admin.py): router · Admin-only management and analytics endpoints · `NagarSetu-Backend/app/routers/admin.py`
- [Complaint service](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/services/complaint_service.py): business logic · Orchestrates complaint persistence and ML enrichment · `NagarSetu-Backend/app/services/complaint_service.py`
- [Models](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/models): ORM entities · User and complaint database entities · `NagarSetu-Backend/app/models`
- [Schemas](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/app/schemas): Pydantic contracts · Request and response shapes for users and complaints · `NagarSetu-Backend/app/schemas`
- [Inference API](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/inference_api.py): ML serving · Backend runtime that serves image classification predictions · `NagarSetu-Backend/inference_api.py`

### ML

Inference runtime and training pipeline

- [ML pipeline](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-ML/train.py): training/export · Offline dataset preparation, training, evaluation, and model export · `NagarSetu-ML/train.py`
- [Model artifacts](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/ml_models/nagarsetu.onnx): exported model · Deployed ONNX and PyTorch artifacts plus class labels · `NagarSetu-Backend/ml_models/nagarsetu.onnx`

### Data

Persistent storage and local artifacts

- [PostgreSQL](https://github.com/aaditya02123/nagarsetu/blob/main/NagarSetu-Backend/app/core/database.py): relational store · Primary transactional persistence for users and complaints · `NagarSetu-Backend/app/core/database.py`
- [Uploads](https://github.com/aaditya02123/nagarsetu/tree/main/NagarSetu-Backend/uploads): file store · Stored complaint images and media files · `NagarSetu-Backend/uploads`

## Connections

- React app → API client: calls · UI uses the API client to reach the backend
- React app → Route guard: uses · Routes are wrapped by the auth guard where needed
- Citizen pages → React app: rendered by · Citizen pages are part of the main React app
- Admin UI → Route guard: protected by · Admin routes are gated from unprivileged access
- API client → API app: HTTP · Frontend submits auth, complaint, and admin requests
- API app → Routers: mounts · Application entrypoint registers API routers
- API app → Core: initializes · Loads config, database, and security setup
- API app → Auth middleware: applies · Installs request protection for privileged routes
- Routers → Auth API: includes · Exposes authentication endpoints
- Routers → Complaint API: includes · Exposes citizen complaint endpoints
- Routers → Admin API: includes · Exposes admin management endpoints
- Auth API → Core: uses · Auth depends on security and database wiring
- Auth API → Schemas: validates · Uses user/auth request and response contracts
- Complaint API → Complaint service: delegates · Complaint routes hand off to business logic
- Complaint service → Models: persists · Service writes complaint and user records
- Complaint service → Schemas: maps · Transforms domain data into API responses
- Complaint service → Inference API: predicts · Forwards complaint media for classification
- Inference API → Model artifacts: loads · Serving runtime uses exported model files
- Complaint service → PostgreSQL: reads/writes · Complaint and user data are stored in PostgreSQL
- Complaint service → Uploads: stores · Complaint images are saved on disk
- ML pipeline → Model artifacts: produces · Training pipeline exports deployable model artifacts