How stavanrkhobare/civiclens works
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: app Frontend App · api API App · workers Workers · reports Reports API
Components 27
Users
Human actors using the system
- Citizens · Public users submitting and browsing complaints
- Ward Managers · Ward-scoped operators handling complaints
- Ward Supervisors · Reviewers verifying manager submissions
Frontend
Next.js user-facing app
- Frontend App · User-facing Next.js application
civiclens-frontend/src/app - Auth Context · Client-side role and session handling
civiclens-frontend/src/app/context/AuthContext.js - Shared UI · Navbar, footer, navigation, and complaint cards
civiclens-frontend/src/app/components - Public Pages · Home, complaints, about, and post-complaint flows
civiclens-frontend/src/app - My Complaints · Logged-in user complaint history
civiclens-frontend/src/app/my-complaints/page.js - Manager UI · Manager dashboard and complaint handling
civiclens-frontend/src/app/manager - Supervisor UI · Supervisor dashboard, complaints, and submissions
civiclens-frontend/src/app/supervisor
Backend API
Next.js API service
- API App · Backend contract exposed through app/api
civiclens-backend/app/api - Complaints API · Create, update, and inspect complaint records
civiclens-backend/app/api/complaints - Analytics API · Complaint analytics for managers
civiclens-backend/app/api/analytics/route.js - Remarks API · Manager remarks and issue notes
civiclens-backend/app/api/remarks/route.js - Reports API · PDF submission, download, and submissions listing
civiclens-backend/app/api/reports - Supervisor Verify · Supervisor report verification endpoint
civiclens-backend/app/api/supervisor-verify/route.js - Health & Test · Health check and database test endpoints
civiclens-backend/app/api/health/route.js
ML Pipeline
Python processing and enrichment service
- ML Service · FastAPI and Celery processing entrypoint
ML pipeline/fastapi_app.py - Task Pipeline · Complaint processing orchestration
ML pipeline/tasks/pipeline.py - Workers · Classification and summary workers
ML pipeline/workers - Model Assets · DistilBERT classifier and tokenizer artifacts
ML pipeline/civiclens_model - Geocoding Data · Ward boundary and geocoding inputs
ML pipeline/address_data/bbmp_ward_data.kml
Shared Data
Database and storage boundary
- Supabase · Database and object storage for complaints and PDFs
- ComplaintTable · Raw citizen submissions
- SummaryTable · Aggregated and ward-mapped complaints
- SummaryComplaintMap · Links raw complaints to processed summaries
- Report Metadata · Stored PDF path, hash, and workflow status
Connections 34
- 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