# sakbaj/jansunwaiapplication architecture

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

- Interactive diagram: https://gitdiagram.com/sakbaj/jansunwaiapplication
- Repository: https://github.com/sakbaj/jansunwaiapplication

## Overview

#### Purpose and Runtime
LNN-Nivaaran is a municipal grievance-management demo platform: citizens submit text, audio, and image reports; AI classifies and routes them; officers manage queues; administrators view operational analytics. It is a Next.js App Router application running React 19, with Tailwind styling. The root shell and public landing entry are `src/app/layout.tsx` and `src/app/page.tsx`.

#### Route-Level Entry Points and Access
Primary portals are citizen submission/tracking (`src/app/citizen/page.tsx`), officer operations (`src/app/officer/page.tsx`), and administration (`src/app/admin/page.tsx`). Login and role gating are centered in `src/app/login/page.tsx`, with auth/session behavior in `src/lib/auth.ts`. Public informational/API documentation routes sit under `src/app/help/page.tsx` and `src/app/api-docs/page.tsx`.

#### Citizen Intake Pipeline
The citizen complaint UI collects complaint content, location, and attachments through `src/components/citizen/ComplaintForm.tsx`, embedded by `src/app/citizen/page.tsx`. It calls server endpoints for classification and transcription: `src/app/api/classify/route.ts` and `src/app/api/transcribe/route.ts`. Tracking and post-submission communication are represented by `src/components/citizen/TrackingTimeline.tsx` and `src/components/citizen/AIAgentFollowUpPanel.tsx`.

#### AI Boundary and Fallbacks
Gemini 2.5 Flash is the optional external AI service, configured through `GEMINI_API_KEY`. Server-side API routes isolate Gemini-backed multimodal classification and audio transcription from browser components. If unavailable, local heuristic behavior is implemented in `src/lib/ai.ts`, using department/keyword definitions from `src/data/departments.ts`; this supports offline/demo behavior rather than making AI availability a hard dependency.

#### Complaint State, Routing, and Hotspots
The core domain model is defined in `src/types/index.ts`. Complaint data and browser-side persistence/query simulation are handled in `src/lib/complaints.ts`, seeded from `src/data/complaints.ts`. This layer recomputes active complaints grouped by area and category: clusters of at least two become hotspots, receive elevated priority, and return to normal as resolved items reduce a cluster. Grievance submission has a dedicated persistence-facing API boundary at `src/app/api/grievance/submit/route.ts`.

#### Operational and Analytics Views
Officer workflows consume routed, prioritized complaint state in `src/app/officer/page.tsx`; this is the control point for department queues and status/resolution updates feeding citizen tracking. The administration view aggregates complaint telemetry in `src/app/admin/page.tsx`, with visualization logic in `src/components/admin/AnalyticsCharts.tsx`. Citizen-facing hotspot visualization is isolated in `src/components/citizen/ComplaintHeatmap.tsx`, using the Leaflet/React Leaflet GIS stack.

#### Infrastructure and Persistence Posture
The shipped architecture is primarily a client-side/demo state model, augmented by Next.js route handlers for AI and grievance submission. A Supabase schema exists at `supabase/schema.sql`, indicating an intended relational persistence backend, but the core runtime data layer currently lives under `src/lib/complaints.ts`. Browser APIs support geolocation and local/cross-tab session behavior; Google Gemini is the principal external service.

Main entry points: [`src/lib/complaints.ts`](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/complaints.ts) (Complaint state & hotspots), [`src/app/layout.tsx`](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/layout.tsx) (App shell & landing), [`src/app/citizen/page.tsx`](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/citizen/page.tsx) (Citizen portal), [`src/components/citizen/ComplaintForm.tsx`](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/ComplaintForm.tsx) (Complaint intake form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Portals & UI"]
  node_app_shell["App shell &amp; landing<br/>Next.js entry<br/>[layout.tsx]"]
  node_auth["Login &amp; role sessions<br/>auth library<br/>[auth.ts]"]
  node_login["Login<br/>route page<br/>[page.tsx]"]
  node_citizen_portal["Citizen portal<br/>route page<br/>[page.tsx]"]
  node_complaint_form["Complaint intake form<br/>React component<br/>[ComplaintForm.tsx]"]
  node_tracking["Tracking &amp; AI follow-up<br/>citizen components"]
  node_heatmap["Complaint heatmap<br/>GIS component"]
  node_officer_portal["Officer operations<br/>route page<br/>[page.tsx]"]
  node_admin_portal["Administration<br/>route page<br/>[page.tsx]"]
  node_analytics["Analytics charts<br/>React component"]
end

subgraph group_api["Server boundaries"]
  node_ai_routes{{"Classification &amp; transcription<br/>route handlers<br/>[route.ts]"}}
  node_grievance_api{{"Grievance submission<br/>route handler<br/>[route.ts]"}}
end

subgraph group_domain["Domain state"]
  node_complaints_state[("Complaint state &amp; hotspots<br/>client data layer<br/>[complaints.ts]")]
  node_domain_model["Complaint domain model<br/>TypeScript types<br/>[index.ts]"]
  node_seed_data["Seed complaints<br/>demo data<br/>[complaints.ts]"]
  node_ai_fallback["Local AI fallback<br/>heuristic engine<br/>[ai.ts]"]
  node_departments["Department definitions<br/>routing data<br/>[departments.ts]"]
end

subgraph group_external["External &amp; planned persistence"]
  node_gemini(("Google Gemini<br/>external AI service"))
  node_supabase_schema[("Supabase schema<br/>planned relational persistence<br/>[schema.sql]")]
end

node_app_shell -->|"serves"| node_login
node_login -->|"uses"| node_auth
node_app_shell -->|"serves"| node_citizen_portal
node_app_shell -->|"serves"| node_officer_portal
node_app_shell -->|"serves"| node_admin_portal
node_citizen_portal -->|"embeds"| node_complaint_form
node_citizen_portal -->|"shows"| node_tracking
node_citizen_portal -->|"shows"| node_heatmap
node_complaint_form -->|"classifies/transcribes"| node_ai_routes
node_complaint_form -->|"submits"| node_grievance_api
node_ai_routes -->|"optional request"| node_gemini
node_ai_routes -.->|"falls back to"| node_ai_fallback
node_ai_fallback -->|"routes with"| node_departments
node_grievance_api -->|"persists to demo state"| node_complaints_state
node_complaints_state -->|"uses"| node_domain_model
node_complaints_state -->|"initializes from"| node_seed_data
node_officer_portal -->|"updates queues and status"| node_complaints_state
node_tracking -->|"reads status"| node_complaints_state
node_heatmap -->|"reads hotspots"| node_complaints_state
node_admin_portal -->|"renders"| node_analytics
node_analytics -->|"aggregates telemetry"| node_complaints_state
node_supabase_schema -.->|"future persistence target"| node_complaints_state

click node_app_shell "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/layout.tsx"
click node_auth "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/auth.ts"
click node_login "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/login/page.tsx"
click node_citizen_portal "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/citizen/page.tsx"
click node_complaint_form "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/ComplaintForm.tsx"
click node_tracking "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/TrackingTimeline.tsx"
click node_heatmap "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/ComplaintHeatmap.tsx"
click node_officer_portal "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/officer/page.tsx"
click node_admin_portal "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/admin/page.tsx"
click node_analytics "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/admin/AnalyticsCharts.tsx"
click node_ai_routes "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/api/classify/route.ts"
click node_grievance_api "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/api/grievance/submit/route.ts"
click node_complaints_state "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/complaints.ts"
click node_domain_model "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/types/index.ts"
click node_seed_data "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/data/complaints.ts"
click node_ai_fallback "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/ai.ts"
click node_departments "https://github.com/sakbaj/jansunwaiapplication/blob/main/src/data/departments.ts"
click node_supabase_schema "https://github.com/sakbaj/jansunwaiapplication/blob/main/supabase/schema.sql"

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_app_shell,node_auth,node_login,node_citizen_portal,node_complaint_form,node_tracking,node_heatmap,node_officer_portal,node_admin_portal,node_analytics toneBlue
class node_ai_routes,node_grievance_api toneAmber
class node_complaints_state,node_domain_model,node_seed_data,node_ai_fallback,node_departments toneMint
class node_gemini,node_supabase_schema toneRose
```

## Components

### Portals & UI

- [App shell & landing](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/layout.tsx): Next.js entry · `src/app/layout.tsx`
- [Login & role sessions](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/auth.ts): auth library · `src/lib/auth.ts`
- [Login](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/login/page.tsx): route page · `src/app/login/page.tsx`
- [Citizen portal](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/citizen/page.tsx): route page · `src/app/citizen/page.tsx`
- [Complaint intake form](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/ComplaintForm.tsx): React component · Collects text, location, audio, and image reports. · `src/components/citizen/ComplaintForm.tsx`
- [Tracking & AI follow-up](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/TrackingTimeline.tsx): citizen components · `src/components/citizen/TrackingTimeline.tsx`
- [Complaint heatmap](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/citizen/ComplaintHeatmap.tsx): GIS component · Leaflet-based citizen hotspot visualization. · `src/components/citizen/ComplaintHeatmap.tsx`
- [Officer operations](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/officer/page.tsx): route page · Manages department queues and resolution status. · `src/app/officer/page.tsx`
- [Administration](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/admin/page.tsx): route page · `src/app/admin/page.tsx`
- [Analytics charts](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/components/admin/AnalyticsCharts.tsx): React component · `src/components/admin/AnalyticsCharts.tsx`

### Server boundaries

- [Classification & transcription](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/api/classify/route.ts): route handlers · Isolates multimodal AI operations from the browser. · `src/app/api/classify/route.ts`
- [Grievance submission](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/app/api/grievance/submit/route.ts): route handler · `src/app/api/grievance/submit/route.ts`

### Domain state

- [Complaint state & hotspots](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/complaints.ts): client data layer · Persists demo state and elevates clusters of two or more active complaints. · `src/lib/complaints.ts`
- [Complaint domain model](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/types/index.ts): TypeScript types · `src/types/index.ts`
- [Seed complaints](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/data/complaints.ts): demo data · `src/data/complaints.ts`
- [Local AI fallback](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/lib/ai.ts): heuristic engine · Provides offline classification when Gemini is unavailable. · `src/lib/ai.ts`
- [Department definitions](https://github.com/sakbaj/jansunwaiapplication/blob/main/src/data/departments.ts): routing data · `src/data/departments.ts`

### External & planned persistence

- **Google Gemini**: external AI service · Optional Gemini 2.5 Flash integration.
- [Supabase schema](https://github.com/sakbaj/jansunwaiapplication/blob/main/supabase/schema.sql): planned relational persistence · Schema exists, but is not the core runtime data store. · `supabase/schema.sql`

## Connections

- App shell & landing → Login: serves
- Login → Login & role sessions: uses
- App shell & landing → Citizen portal: serves
- App shell & landing → Officer operations: serves
- App shell & landing → Administration: serves
- Citizen portal → Complaint intake form: embeds
- Citizen portal → Tracking & AI follow-up: shows
- Citizen portal → Complaint heatmap: shows
- Complaint intake form → Classification & transcription: classifies/transcribes
- Complaint intake form → Grievance submission: submits
- Classification & transcription → Google Gemini: optional request
- Classification & transcription → Local AI fallback: falls back to
- Local AI fallback → Department definitions: routes with
- Grievance submission → Complaint state & hotspots: persists to demo state
- Complaint state & hotspots → Complaint domain model: uses
- Complaint state & hotspots → Seed complaints: initializes from
- Officer operations → Complaint state & hotspots: updates queues and status
- Tracking & AI follow-up → Complaint state & hotspots: reads status
- Complaint heatmap → Complaint state & hotspots: reads hotspots
- Administration → Analytics charts: renders
- Analytics charts → Complaint state & hotspots: aggregates telemetry
- Supabase schema → Complaint state & hotspots: future persistence target