Complaint categories
42+
Mapped across major Delhi civic authorities.
JanSamadhan platform documentation
Professional documentation for product, engineering, and operations teams.
This page consolidates system intent, architecture, lifecycle guarantees, and operational behavior in one readable reference. It is designed for high scanning speed while preserving technical depth.
NOTE: JanSamadhan is a Private R&D Prototype. This platform is a technology demonstration and is not an official government service.
Technical docsArchitecture-firstRole workflowsAPI and DB referenceOps readiness
Executive Snapshot
High-speed briefing on platform scope, guarantees, and why this implementation is operationally distinct.
Authority zones
9
Department-aware routing and visibility.
API endpoints
56+
FastAPI, Next.js handlers, and AI service.
RLS policies
28
Department isolation at database layer.
Role portals
4
Citizen, Authority, Worker, and Admin.
Voice languages
10
Multilingual STT for complaint intake.
Core design principle: high-impact rules are enforced at transaction and database policy level, not only at interface level.
Problem Definition
The system addresses fragmentation, low transparency, duplicate noise, and weak closure accountability in civic operations.
The operational failure mode in legacy civic systems is not only ticket intake. It is the disconnected chain from complaint submission to assignment, field execution, and closure verification.
Citizens lose confidence when timelines are opaque. Authorities lose efficiency when duplicates flood the queue. Workers lose time when location and context are weak. This documentation focuses on structural controls that directly address those gaps.
| Pain point | Ground reality | Design response |
|---|---|---|
| No single window | Citizens must already know which department handles which issue. | Unified intake with AI-assisted category and authority prediction. |
| Zero visibility | Complaints disappear without status context or timeline confidence. | Lifecycle state machine with immutable ticket history. |
| Duplicate noise | One pothole can create dozens of separate complaints. | PostGIS radius-based dedup with upvote merge behavior. |
| Language barrier | English-only forms block broad participation. | Hindi and multilingual voice ingestion via STT pipeline. |
| No spatial intelligence | Authorities cannot identify hotspot clusters early. | DIGIPIN + map-first dashboards + nearby complaint discovery. |
| Worker context gap | Field teams get vague assignments with little proof context. | Mobile-first worker dashboard with maps, SLA timer, and proof upload. |
| Jurisdiction overlap | Wrong-department routing delays closure and accountability. | Department-scoped authority view enforced by JWT-backed RLS. |
Platform Solution
Four role portals share one lifecycle model, one source of truth, and enforcement controls at the database layer.
Citizen portal
Complaint filing via Seva, voice, map pin, status tracking, and rating loop.
Authority dashboard
Department-scoped triage, worker assignment, escalation, and internal notes.
Worker interface
Mobile-first web task execution with navigation, SLA countdown, and proof upload.
Admin control panel
Cross-system moderation, analytics, CCTV oversight, and account governance.
One citizen-facing intake surface, isolated authority views, and centralized governance data for admin operations.
Why This Is Different
Differentiators are tied to enforceable implementation choices, not cosmetic feature claims.
| Capability | Implementation | Operational impact |
|---|---|---|
| AI complaint intake | Gemini classifies category, severity, and likely authority from free text. | Reduces form friction and improves first-route accuracy. |
| DIGIPIN location identity | 10-character India Post code generated from pin-selected coordinates. | Improves field navigation precision and address stability. |
| PostGIS duplicate suppression | 20m radius check before insert; existing complaint can be upvoted instead. | Prevents spam-like duplication and amplifies signal quality. |
| DB-level department isolation | RLS policies enforce row visibility using role and department claims. | Blocks cross-department leakage even if UI logic is bypassed. |
| Race-safe assignment | FOR UPDATE locking inside assignment RPC. | Prevents concurrent worker double-assignment. |
| Auto-escalation on breach | Cron-callable RPC escalates overdue in-progress tickets. | Removes dependency on manual deadline monitoring. |
| CCTV reliability engine | Burst-based multi-frame consensus before auto ticket creation. | Reduces false positives from single noisy frames. |
| Immutable audit trail | Ticket history rows persist key state and action transitions. | Improves traceability for citizen trust and admin review. |
End-to-End Complaint Journey
A deterministic lifecycle path from citizen intake to field proof and confirmation feedback.
- Citizen reports issue in Hindi, English, or voice through Seva or manual form.
- System enriches payload with category, severity, authority hint, and DIGIPIN coordinates.
- Duplicate check runs with PostGIS distance logic before complaint creation.
- Ticket is created with SLA deadline and notification payloads for citizen tracking.
- Authority dashboard surfaces ticket in department-scoped queue and assigns field worker.
- Worker navigates to location, updates status, and uploads proof evidence on completion.
- Citizen receives closure message and can confirm or reopen within policy limits.
- Ticket history preserves every transition for analytics and accountability.
Example target outcome: issue reported, routed, assigned, resolved with proof, and citizen-confirmed within SLA.
Trust and Accountability
Key guarantees are anchored in policies, triggers, and transactional functions that are hard to bypass.
- No duplicate ticket is inserted for the same category inside configured distance checks.
- Invalid lifecycle transitions are blocked by trigger-level checks before commit.
- Authorities cannot query complaints outside their department scope via RLS.
- Assignment race conditions are blocked with row locks in assignment RPC logic.
- SLA breach escalation can run from cron without frontend or API availability.
- Severity escalation from community upvotes is monotonic and never decreases.
- DIGIPIN location encoding does not require an online geocoding API call.
Core Systems Breakdown
Subsystem-level view of intake, spatial logic, escalation, surveillance, engagement, and governance.
| System | Behavior | Operational value |
|---|---|---|
| AI intake and Seva chatbot | Classifies complaint text, proposes category and priority, supports multilingual prompts. | Higher completion rate for non-technical citizens. |
| DIGIPIN and map intelligence | Converts pin location to stable code and supports map-driven workflow routing. | Accurate field navigation and geospatial analytics. |
| Duplicate and upvote engine | Identifies proximity duplicates and shifts users to vote-based amplification. | Cleaner queue quality and better prioritization signal. |
| SLA and escalation engine | Evaluates deadlines and escalates pending tickets via background function. | Consistent deadline governance with minimal manual intervention. |
| CCTV and verification loop | Analyzes camera bursts, proposes incidents, supports repaired/not-repaired verification. | Extends detection coverage beyond manual citizen reports. |
| Gamification and wallet | Awards points for constructive participation and applies penalties for abuse. | Promotes participation while deterring spam behavior. |
| Notification pipeline | Sends email and WhatsApp events with deep links and closure prompts. | Maintains citizen loop continuity after submission. |
| Admin analytics and governance | Aggregates platform metrics, department performance, and operational health. | Supports planning, staffing, and policy interventions. |
Role Flows and Boundaries
Responsibilities and boundaries per role to preserve clarity, safety, and operational ownership.
| Role | Can do | Cannot do |
|---|---|---|
| Citizen | Create complaints, track status, upvote, rate resolution, reopen within policy. | Assign workers, view internal authority notes, change department ownership. |
| Authority | Review department tickets, assign workers, escalate, add internal notes. | View other departments when RLS constraints are active. |
| Worker | View assigned tickets, update status, upload proof, request materials. | Self-assign tickets or access unrelated workers' queues. |
| Admin | Cross-platform moderation, analytics, user management, and CCTV operations. | Bypass accountability records; ticket history remains auditable. |
System Architecture
Layered architecture with explicit boundaries for client, APIs, data, integrations, and cloud runtime.
| Layer | Stack | Notes |
|---|---|---|
| Client | Next.js 15 + React 19 | Role-specific portals, map workflows, and citizen-facing accountability views. |
| Application APIs | FastAPI + Next.js route handlers + AI microservice | Complaint intake, role workflows, notifications, CCTV processing, and admin controls. |
| Data | PostgreSQL 15 + PostGIS + Supabase Storage + Redis | RLS, triggers, RPC transactions, spatial indexing, and cache/session support. |
| External integrations | Google Gemini, Sarvam STT, Mappls, WhatsApp Cloud API, Resend | Gemini use assumes paid API access; no free-tier dependency is documented. |
| Infrastructure | GCP Cloud Run + Cloud Build + Secret Manager | Three-service deployment topology with containerized release workflow. |
Data Model and RPCs
Enums, triggers, RLS, and RPC transactions form the core integrity model of the platform.
complaint_statusseverity_levelworker_availability
Core setup sequence: define enum types, create dependency-ordered tables, apply spatial indexes, register triggers, create RPC functions, then enable and verify RLS policies.
| RPC | Purpose |
|---|---|
| check_for_duplicate_report | 20m duplicate detection before complaint insert. |
| find_duplicate_complaints_v2 | Extended duplicate scan with status and radius controls. |
| increment_upvote_count | Atomic upvote plus effective severity recalculation. |
| assign_worker_to_complaint | Assignment with row locking for race protection. |
| check_sla_breaches | Escalates overdue assigned or in-progress complaints. |
| nearest_urgent_complaint | Proximity and urgency-aware dispatch helper. |
| get_nearby_complaints | Distance-ranked complaint discovery for maps. |
| award_points | Gamification point updates in a single transaction. |
| redeem_reward | Atomic reward redemption and balance validation. |
| update_complaint_status_citizen | Citizen confirm/reopen action with policy checks. |
API Surface
Representative endpoint inventory across FastAPI, Next.js routes, and environment contract requirements.
FastAPI core endpoints
| Endpoint | Method | Purpose |
|---|---|---|
| /analyze | POST | AI-assisted complaint preview and routing suggestion. |
| /confirm | POST | Complaint creation, routing, dedup, and notifications. |
| /citizen/tickets | GET | Citizen ticket feed with status visibility. |
| /citizen/nearby | GET | Map-based nearby issue discovery. |
| /api/authority/assign | PATCH | Authority worker assignment operation. |
| /api/authority/dashboard | GET | Authority queue and SLA dashboard data. |
| /api/worker/dashboard | GET | Worker task list and execution context. |
| /api/admin/analytics | GET | Platform-level operational analytics. |
| /whatsapp/webhook | GET/POST | WhatsApp verification and bot message handling. |
| /cctv/analyze_live | POST | CCTV frame burst analysis with reliability checks. |
| /cctv/verify | POST | Verification feedback for camera-detected incidents. |
Next.js app route handlers
| Endpoint | Method | Purpose |
|---|---|---|
| /api/complaints | POST/PATCH | Complaint create, update, and upvote operations. |
| /api/chat | POST | Gemini proxy with fallback model handling. |
| /api/stt | POST | Sarvam STT proxy for multilingual voice submission. |
| /api/verify-recaptcha | POST | Server-side captcha verification. |
| /api/citizen/wallet | GET/POST | Wallet points, rewards, and redemption state. |
| /api/citizen/leaderboard | GET | Public engagement leaderboard data. |
| /api/admin/authorities | GET/POST/PATCH | Authority account management. |
| /api/admin/workers | GET/POST/PATCH | Worker account management. |
| /api/admin/complaints/spam | POST | Spam moderation and penalty flow. |
| /api/admin/system/sync-wallets | POST | Backfill wallet balances for existing users. |
Key environment variables
| Variable | Purpose |
|---|---|
| NEXT_PUBLIC_SUPABASE_URL | Supabase project URL for client access. |
| NEXT_PUBLIC_SUPABASE_ANON_KEY | Public key for browser-level Supabase operations. |
| SUPABASE_SERVICE_ROLE_KEY | Privileged server-side key for administrative actions. |
| GEMINI_API_KEY | Google Gemini key for paid API usage. |
| GEMINI_PRIMARY_MODEL | Optional primary model override. |
| GEMINI_FALLBACK_MODEL | Fallback model for quota/model errors. |
| MAPPLS_API_KEY | India-focused geocoding and map enrichment. |
| NEXT_PUBLIC_API_URL | Backend API base URL consumed by web clients. |
| NEXT_PUBLIC_RECAPTCHA_SITE_KEY | Public reCAPTCHA site key. |
| RECAPTCHA_SECRET_KEY | Server-side captcha verification key. |
| SARVAM_API_KEY | Speech-to-text service authentication. |
| RESEND_API_KEY | Transactional email service key. |
| FRONTEND_BASE_URL | Canonical deep-link origin for messages and notifications. |
| AI_SERVICE_URL | AI service endpoint for CCTV proxy operations. |
| REDIS_URL | Cache and session backend URL. |
| WHATSAPP_TOKEN | Meta WhatsApp Cloud API token. |
| WHATSAPP_PHONE_NUMBER_ID | WhatsApp sender configuration. |
| WHATSAPP_VERIFY_TOKEN | Webhook verification token. |
Security and Integrity
Security model combines authentication, RLS, anti-abuse controls, and enforceable transition integrity.
| Control | Detail |
|---|---|
| RLS role isolation | Row access constrained by role and department claims. |
| Status transition validation | Trigger checks block invalid status transitions. |
| Captcha abuse prevention | Server-side reCAPTCHA verification for public intake paths. |
| Assignment lock safety | FOR UPDATE locking prevents concurrent assignment conflicts. |
| Audit trail persistence | State and action records retained for review and governance. |
| Secret management | Runtime secret injection through cloud secret stores. |
| Moderation and penalties | Spam flagging and wallet penalties deter abuse patterns. |
Security guarantees are strongest when enforcement resides in DB policy and transaction logic, not just client code.
Operations and Deployment
Operational model is containerized and split across web, API, and AI services with cloud-native deployment controls.
Deployment topology uses three services: web, API, and AI. Local simulation uses Docker Compose, while production uses Cloud Run with Cloud Build and managed secret injection.
Pre-release checks should validate complaint intake, assignment transactions, deep-link generation, notification channels, and AI-service health before rollout approval.
- Validate FRONTEND_BASE_URL before sending any notification links.
- Ensure pending_closure migration is applied in the target database.
- Verify model and API credentials are loaded from secret manager.
- Run smoke checks for /analyze, /confirm, /api/authority/assign, and /cctv/analyze_live.
Failure Handling / Edge Cases
Production posture requires explicit responses to common failure and abuse scenarios.
| Scenario | System response |
|---|---|
| Gemini quota or model failure | Fallback to manual submission or fallback model path. |
| Duplicate complaint attempt | Pre-submit dedup guides citizen to upvote existing ticket. |
| Worker unavailable mid-task | Authority can reassign; overdue tickets escalate automatically. |
| SLA breach with no manual review | Cron RPC escalates to high-priority authority queue. |
| Single-frame CCTV false positive | Burst consensus threshold suppresses low-confidence incidents. |
| Spam submission bursts | Captcha, moderation queue, and penalties limit abuse impact. |
| Broken deep link | FRONTEND_BASE_URL validation and UUID-based detail links. |
| Concurrent assignment attempts | Second transaction is rejected by lock conflict semantics. |
Comparative Positioning
Comparison against common grievance baseline behavior across accessibility, governance, and closure reliability.
| Dimension | Legacy portals | JanSamadhan |
|---|---|---|
| Language and accessibility | English-heavy forms with high form literacy requirement. | Hindi and multilingual voice-assisted intake with guided flow. |
| Duplicate handling | Repeated records for same incident in dense areas. | Distance-aware dedup and upvote aggregation. |
| Department isolation | Soft segregation; frequent routing confusion. | RLS-backed department boundaries and role isolation. |
| SLA governance | Manual follow-up and limited breach visibility. | Automated escalation and dashboard-level breach surfacing. |
| Resolution proof | Closure may happen without contextual field evidence. | Worker proof artifacts and closure confirmation loop. |
| Citizen accountability view | Sparse status context. | Trackable lifecycle with audit-friendly status history. |
Current Scope and Limits
Live, partial, and planned items are separated to prevent ambiguity about production readiness.
| Feature | Status | Notes |
|---|---|---|
| Citizen, Authority, Worker, Admin portals | Live | Role-specific production interfaces are active. |
| Seva chatbot and multilingual voice intake | Live | Gemini and Sarvam flows are integrated in active runtime. |
| DIGIPIN and map-first workflows | Live | Complaint creation and worker navigation pipelines use map coordinates. |
| WhatsApp intake and closure loop | Live (v1) | Menu-driven intake and closure reminders are shipped. |
| CCTV reliability and verification | Live | Burst analysis and verification outcomes are available. |
| Infrastructure-as-code scaffolding | Partial | Folder scaffolds exist; full Terraform rollout remains pending. |
| Service worker offline caching | Planned | Planned enhancement; worker portal is currently web mobile-first, not a PWA. |
| Multi-city rollout | Planned | Current scope emphasizes Delhi confidence before expansion. |
| CPGRAMS bridge integration | Planned | Future interoperability phase. |
Worker operations currently use a mobile-first web dashboard. A dedicated worker PWA is not shipped in current scope.
Roadmap
Roadmap phases are additive and move from city confidence to interoperability and scale.
Phase 1
Delhi pilot with all role portals and core governance controls.
Status: Complete
Phase 2
City expansion playbook for Mumbai, Bengaluru, and Chennai.
Status: Planned
Phase 3
Offline caching and resilience improvements for low-connectivity areas.
Status: Planned
Phase 4
WhatsApp conversational depth expansion beyond v1 flow.
Status: In progress
Phase 5
Cross-platform escalation bridge and inter-jurisdiction routing.
Status: Planned
Phase 6
Future DIGIPIN API alignment and national-scale integrations.
Status: Planned
Glossary
Plain-language definitions for recurring technical terms used throughout this document.
| Term | Plain meaning | Technical meaning |
|---|---|---|
| DIGIPIN | India's location code system. | 10-character location identity from India Post used for precise mapping. |
| RLS | Database row-level access walls. | PostgreSQL policy layer that constrains row visibility by role claims. |
| PostGIS | Spatial extension for PostgreSQL. | Adds geospatial functions such as distance checks for dedup logic. |
| SLA | Complaint deadline contract. | Timing policy for escalation, prioritization, and closure accountability. |
| RPC | Atomic database function call. | Server-side function that runs as a single transaction. |
| FOR UPDATE | Row reservation lock. | Concurrency control used during worker assignment operations. |
| YOLO | Real-time vision model. | Model family used for CCTV incident detection in AI service workflows. |
| pending_closure | Waiting for citizen confirmation. | Lifecycle state between worker resolution and citizen final closure decision. |