# stavanrkhobare/civiclens architecture

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

- Interactive diagram: https://gitdiagram.com/stavanrkhobare/civiclens
- Repository: https://github.com/stavanrkhobare/civiclens

## Overview

1. **Repository shape**
   This is a three-part system: a **Next.js frontend**, a separate **Next.js API/backend**, and a **Python ML/processing pipeline**. The main shared boundary is **Supabase**, which provides the PostgreSQL database and storage for PDFs.

2. **Frontend application boundary**
   `civiclens-frontend` is the user-facing app on port 3000. It uses the Next.js App Router with role-specific pages for **citizens**, **ward managers**, and **ward supervisors**. The frontend is organized around route folders rather than a single SPA state machine.

3. **Role-based UI layers**
   The frontend has distinct surface areas:
   - public complaint browsing and submission
   - “My Complaints” for the logged-in user
   - manager dashboard and complaint handling
   - supervisor dashboard, complaints, and submissions
   Shared UI building blocks include the navbar, footer, complaint cards, and an auth context used to drive role-based navigation and access.

4. **Backend API boundary**
   `civiclens-backend` is a separate Next.js app exposing only API routes under `app/api`. This backend is the contract between the frontend and the data layer. Its routes are grouped by business capability: complaints, analytics, remarks, report submission/download, supervisor verification, health checks, and database tests.

5. **Core complaint data flow**
   The central workflow starts when a citizen submits a complaint through the frontend. The raw complaint is stored first, then later appears in a processed/merged form. The system’s data model is explicitly split between:
   - `ComplaintTable` for raw submissions
   - `SummaryTable` for processed/aggregated complaints
   - `SummaryComplaintMap` to link many raw complaints to one processed summary

6. **Processing and aggregation boundary**
   The repository includes a Python `ML pipeline` service that appears to handle complaint processing, classification, and summarization. It contains Celery setup, a FastAPI entrypoint, workers for classification and summary generation, and a task pipeline. This suggests asynchronous/offline processing rather than doing all enrichment inside the Next.js API layer.

7. **ML and geospatial enrichment**
   The ML pipeline ships with model artifacts under `civiclens_model`, including a DistilBERT-based classifier and tokenizer files, plus a label encoder. It also includes ward boundary data (`bbmp_ward_data.kml`) and geocoding code, which indicates that complaint text is likely normalized, classified, and mapped to a ward before being written back to the summary tables.

8. **Manager workflow**
   Managers operate on ward-scoped complaints. Their flow is: inspect analytics, update complaint status, add remarks, resolve issues, then generate a report. The backend supports report submission and download, and the database stores report metadata such as PDF path, hash, and workflow status.

9. **Supervisor workflow**
   Supervisors review manager-submitted reports. The backend exposes a submissions list and a verification endpoint, and the frontend has dedicated supervisor pages for dashboards and submission review. Verification is a separate workflow state from manager resolution, so the system distinguishes “resolved by manager” from “verified by supervisor.”

10. **Report generation and storage**
   Reports are generated as PDFs in the backend, then stored in Supabase Storage. The database tracks the generated file URL/path and a hash, which makes the report artifact a first-class persisted object rather than a transient download response.

11. **Authentication and access control boundary**
   The system uses simple development-time auth with hardcoded role credentials, and the frontend manages session state locally. That means authorization is mostly enforced by UI flow and API conventions rather than by a hardened identity service. Role and ward assignment are derived from the username format.

12. **Deployment and runtime separation**
   The two Next.js apps are independently deployable and both have Vercel configuration, which implies separate deployment units for the frontend and backend. The Python ML pipeline is a third runtime with its own dependencies and startup scripts, likely deployed as a worker/service alongside the Next.js stack.

13. **What to draw as the main architecture**
   The important diagram boundaries are:
   - **Users** → **Frontend**
   - **Frontend** → **Backend API**
   - **Backend API** ↔ **Supabase database/storage**
   - **Backend/ML pipeline** → **processed complaint tables**
   - **Manager/Supervisor workflows** as separate role-specific paths over the same complaint data
   The system is essentially a civic case-management platform with a processing layer that transforms raw citizen submissions into ward-level operational records.

Main entry points: [`civiclens-frontend/src/app`](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app) (Frontend App), [`civiclens-backend/app/api`](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api) (API App), [`ML pipeline/workers`](https://github.com/stavanrkhobare/civiclens/tree/HEAD/ML%20pipeline/workers) (Workers), [`civiclens-backend/app/api/reports`](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api/reports) (Reports API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["Users"]
  node_citizens(("Citizens<br/>role"))
  node_managers(("Ward Managers<br/>role"))
  node_supervisors(("Ward Supervisors<br/>role"))
end

subgraph group_frontend["Frontend"]
  node_fe_app["Frontend App<br/>nextjs app"]
  node_fe_auth["Auth Context<br/>session state<br/>[AuthContext.js]"]
  node_fe_nav["Shared UI<br/>ui shell"]
  node_fe_public["Public Pages<br/>citizen routes"]
  node_fe_my["My Complaints<br/>citizen view<br/>[page.js]"]
  node_fe_manager["Manager UI<br/>manager routes"]
  node_fe_supervisor["Supervisor UI<br/>supervisor routes"]
end

subgraph group_backend["Backend API"]
  node_be_app["API App<br/>nextjs api"]
  node_be_complaints["Complaints API<br/>complaint routes"]
  node_be_analytics["Analytics API<br/>metrics routes<br/>[route.js]"]
  node_be_remarks["Remarks API<br/>comment routes<br/>[route.js]"]
  node_be_reports["Reports API<br/>report routes"]
  node_be_verify["Supervisor Verify<br/>verification route<br/>[route.js]"]
  node_be_health["Health & Test<br/>ops routes<br/>[route.js]"]
end

subgraph group_ml["ML Pipeline"]
  node_ml_entry["ML Service<br/>python service<br/>[fastapi_app.py]"]
  node_ml_tasks["Task Pipeline<br/>async pipeline<br/>[pipeline.py]"]
  node_ml_workers["Workers"]
  node_ml_model["Model Assets<br/>nlp model"]
  node_ml_geo["Geocoding Data<br/>ward enrichment<br/>[bbmp_ward_data.kml]"]
end

subgraph group_shared["Shared Data"]
  node_supabase[("Supabase<br/>postgres/storage")]
  node_raw_table[("ComplaintTable<br/>raw complaints")]
  node_summary_table[("SummaryTable<br/>processed complaints")]
  node_map_table[("SummaryComplaintMap<br/>mapping table")]
  node_report_meta[("Report Metadata<br/>pdf records")]
end

node_citizens -->|"use"| node_fe_app
node_managers -->|"use"| node_fe_app
node_supervisors -->|"use"| node_fe_app
node_fe_app -->|"drives"| node_fe_auth
node_fe_app -->|"renders"| node_fe_nav
node_fe_app -->|"hosts"| node_fe_public
node_fe_app -->|"routes"| node_fe_my
node_fe_app -->|"routes"| node_fe_manager
node_fe_app -->|"routes"| node_fe_supervisor
node_fe_app -->|"calls"| node_be_app
node_be_app -->|"exposes"| node_be_complaints
node_be_app -->|"exposes"| node_be_analytics
node_be_app -->|"exposes"| node_be_remarks
node_be_app -->|"exposes"| node_be_reports
node_be_app -->|"exposes"| node_be_verify
node_be_app -->|"exposes"| node_be_health
node_be_app -->|"reads/writes"| node_supabase
node_ml_entry -->|"orchestrates"| node_ml_tasks
node_ml_tasks -->|"dispatches"| node_ml_workers
node_ml_workers -->|"uses"| node_ml_model
node_ml_workers -->|"enriches"| node_ml_geo
node_ml_workers -->|"writes"| node_supabase
node_supabase -->|"stores"| node_raw_table
node_supabase -->|"stores"| node_summary_table
node_supabase -->|"stores"| node_map_table
node_supabase -->|"stores"| node_report_meta
node_be_reports -->|"stores"| node_supabase
node_be_verify -->|"updates"| node_report_meta
node_be_complaints -->|"creates"| node_raw_table
node_ml_workers -->|"materializes"| node_summary_table
node_ml_workers -->|"links"| node_map_table
node_be_analytics -->|"queries"| node_summary_table
node_be_reports -->|"reads"| node_summary_table
node_be_verify -->|"confirms"| node_be_reports

click node_fe_app "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app"
click node_fe_auth "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-frontend/src/app/context/AuthContext.js"
click node_fe_nav "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/components"
click node_fe_public "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app"
click node_fe_my "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-frontend/src/app/my-complaints/page.js"
click node_fe_manager "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/manager"
click node_fe_supervisor "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/supervisor"
click node_be_app "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api"
click node_be_complaints "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api/complaints"
click node_be_analytics "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/analytics/route.js"
click node_be_remarks "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/remarks/route.js"
click node_be_reports "https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api/reports"
click node_be_verify "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/supervisor-verify/route.js"
click node_be_health "https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/health/route.js"
click node_ml_entry "https://github.com/stavanrkhobare/civiclens/blob/main/ML pipeline/fastapi_app.py"
click node_ml_tasks "https://github.com/stavanrkhobare/civiclens/blob/main/ML pipeline/tasks/pipeline.py"
click node_ml_workers "https://github.com/stavanrkhobare/civiclens/tree/main/ML pipeline/workers"
click node_ml_model "https://github.com/stavanrkhobare/civiclens/tree/main/ML pipeline/civiclens_model"
click node_ml_geo "https://github.com/stavanrkhobare/civiclens/blob/main/ML pipeline/address_data/bbmp_ward_data.kml"

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_citizens,node_managers,node_supervisors toneBlue
class node_fe_app,node_fe_auth,node_fe_nav,node_fe_public,node_fe_my,node_fe_manager,node_fe_supervisor toneAmber
class node_be_app,node_be_complaints,node_be_analytics,node_be_remarks,node_be_reports,node_be_verify,node_be_health toneMint
class node_ml_entry,node_ml_tasks,node_ml_workers,node_ml_model,node_ml_geo toneRose
class node_supabase,node_raw_table,node_summary_table,node_map_table,node_report_meta toneIndigo
```

## Components

### Users

Human actors using the system

- **Citizens**: role · Public users submitting and browsing complaints
- **Ward Managers**: role · Ward-scoped operators handling complaints
- **Ward Supervisors**: role · Reviewers verifying manager submissions

### Frontend

Next.js user-facing app

- [Frontend App](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app): nextjs app · User-facing Next.js application · `civiclens-frontend/src/app`
- [Auth Context](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-frontend/src/app/context/AuthContext.js): session state · Client-side role and session handling · `civiclens-frontend/src/app/context/AuthContext.js`
- [Shared UI](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/components): ui shell · Navbar, footer, navigation, and complaint cards · `civiclens-frontend/src/app/components`
- [Public Pages](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app): citizen routes · Home, complaints, about, and post-complaint flows · `civiclens-frontend/src/app`
- [My Complaints](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-frontend/src/app/my-complaints/page.js): citizen view · Logged-in user complaint history · `civiclens-frontend/src/app/my-complaints/page.js`
- [Manager UI](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/manager): manager routes · Manager dashboard and complaint handling · `civiclens-frontend/src/app/manager`
- [Supervisor UI](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-frontend/src/app/supervisor): supervisor routes · Supervisor dashboard, complaints, and submissions · `civiclens-frontend/src/app/supervisor`

### Backend API

Next.js API service

- [API App](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api): nextjs api · Backend contract exposed through app/api · `civiclens-backend/app/api`
- [Complaints API](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api/complaints): complaint routes · Create, update, and inspect complaint records · `civiclens-backend/app/api/complaints`
- [Analytics API](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/analytics/route.js): metrics routes · Complaint analytics for managers · `civiclens-backend/app/api/analytics/route.js`
- [Remarks API](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/remarks/route.js): comment routes · Manager remarks and issue notes · `civiclens-backend/app/api/remarks/route.js`
- [Reports API](https://github.com/stavanrkhobare/civiclens/tree/main/civiclens-backend/app/api/reports): report routes · PDF submission, download, and submissions listing · `civiclens-backend/app/api/reports`
- [Supervisor Verify](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/supervisor-verify/route.js): verification route · Supervisor report verification endpoint · `civiclens-backend/app/api/supervisor-verify/route.js`
- [Health & Test](https://github.com/stavanrkhobare/civiclens/blob/main/civiclens-backend/app/api/health/route.js): ops routes · Health check and database test endpoints · `civiclens-backend/app/api/health/route.js`

### ML Pipeline

Python processing and enrichment service

- [ML Service](https://github.com/stavanrkhobare/civiclens/blob/HEAD/ML%20pipeline/fastapi_app.py): python service · FastAPI and Celery processing entrypoint · `ML pipeline/fastapi_app.py`
- [Task Pipeline](https://github.com/stavanrkhobare/civiclens/blob/HEAD/ML%20pipeline/tasks/pipeline.py): async pipeline · Complaint processing orchestration · `ML pipeline/tasks/pipeline.py`
- [Workers](https://github.com/stavanrkhobare/civiclens/tree/HEAD/ML%20pipeline/workers): celery workers · Classification and summary workers · `ML pipeline/workers`
- [Model Assets](https://github.com/stavanrkhobare/civiclens/tree/HEAD/ML%20pipeline/civiclens_model): nlp model · DistilBERT classifier and tokenizer artifacts · `ML pipeline/civiclens_model`
- [Geocoding Data](https://github.com/stavanrkhobare/civiclens/blob/HEAD/ML%20pipeline/address_data/bbmp_ward_data.kml): ward enrichment · Ward boundary and geocoding inputs · `ML pipeline/address_data/bbmp_ward_data.kml`

### Shared Data

Database and storage boundary

- **Supabase**: postgres/storage · Database and object storage for complaints and PDFs
- **ComplaintTable**: raw complaints · Raw citizen submissions
- **SummaryTable**: processed complaints · Aggregated and ward-mapped complaints
- **SummaryComplaintMap**: mapping table · Links raw complaints to processed summaries
- **Report Metadata**: pdf records · Stored PDF path, hash, and workflow status

## Connections

- Citizens → Frontend App: use · Public users interact with the frontend
- Ward Managers → Frontend App: use · Managers use the role-specific frontend
- Ward Supervisors → Frontend App: use · Supervisors use the role-specific frontend
- Frontend App → Auth Context: drives · App shell uses client-side role state
- Frontend App → Shared UI: renders · Shared layout and navigation components
- Frontend App → Public Pages: hosts · Citizen-facing routes and forms
- Frontend App → My Complaints: routes · Authenticated complaint history view
- Frontend App → Manager UI: routes · Manager dashboard and complaint flow
- Frontend App → Supervisor UI: routes · Supervisor dashboards and review flow
- Frontend App → API App: calls · Frontend consumes backend APIs
- API App → Complaints API: exposes · Complaint CRUD and status operations
- API App → Analytics API: exposes · Manager analytics endpoint
- API App → Remarks API: exposes · Complaint remarks endpoint
- API App → Reports API: exposes · PDF report submission and download
- API App → Supervisor Verify: exposes · Supervisor verification endpoint
- API App → Health & Test: exposes · Operational health and database checks
- API App → Supabase: reads/writes · API persists and retrieves data
- ML Service → Task Pipeline: orchestrates · Service coordinates asynchronous processing
- Task Pipeline → Workers: dispatches · Pipeline hands work to workers
- Workers → Model Assets: uses · Classification and labeling model artifacts
- Workers → Geocoding Data: enriches · Ward mapping and geocoding inputs
- Workers → Supabase: writes · Processed complaints are persisted
- Supabase → ComplaintTable: stores · Raw complaint submissions
- Supabase → SummaryTable: stores · Processed complaint summaries
- Supabase → SummaryComplaintMap: stores · Raw-to-summary linkage
- Supabase → Report Metadata: stores · PDF paths, hashes, and statuses
- Reports API → Supabase: stores · Report generation persists metadata and artifacts
- Supervisor Verify → Report Metadata: updates · Verification changes report workflow state
- Complaints API → ComplaintTable: creates · Citizen submissions start as raw records
- Workers → SummaryTable: materializes · Aggregation creates processed complaints
- Workers → SummaryComplaintMap: links · Tracks which raw complaints formed a summary
- Analytics API → SummaryTable: queries · Analytics are based on processed complaints
- Reports API → SummaryTable: reads · Reports summarize processed ward complaints
- Supervisor Verify → Reports API: confirms · Supervisor review sits after report submission
