# leopears2008-cell/ai-powered-citizen-grievance-platform architecture

> Architecture diagram of the GitHub repository leopears2008-cell/ai-powered-citizen-grievance-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leopears2008-cell/ai-powered-citizen-grievance-platform
- Repository: https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform

## Overview

#### Purpose and principal workflow

NivaranAI is a bilingual citizen-grievance app: a citizen starts in the browser by speaking or typing a complaint, the React filing flow requests AI classification and duplicate checking, and the citizen can submit and track the grievance. Administrators sign in to review, assign and update grievances, with an AI-assisted resolution-drafting endpoint. The README documents Firebase Auth and Firestore as the platform’s identity and data store; however, sampled server routes also manipulate an in-memory complaint collection, so the persistence story is not fully consistent in the available evidence.

#### Components

##### Browser application and citizen workflow
- **Browser user (Citizen)** — *(external; null repository path)* Initiates complaint filing, tracking and feedback through the public app.
- **React bootstrap and screen router** — `src/main.tsx` and `src/App.tsx` — Mounts the React app, provides shared context, and selects home, filing, tracking, history and administrative screens by active tab.
- **Citizen filing and voice capture** — `src/components/GrievanceForm.tsx` — Captures complaint details and evidence, supports voice entry, presents editable AI results and duplicate matches, and handles confirmation/submission.
- **Citizen tracking and public information** — `src/components/CitizenTracker.tsx` — Presents grievance tracking; related citizen history, map, directory and legal screens are grouped into the app’s screen router.
- **Admin user (Administrator)** — *(external; null repository path)* Signs in to review grievances, manage assignments and status, and request resolution drafts.

##### Shared state and identity
- **Application context and authentication** — `src/context/AppContext.tsx` — Holds navigation, language, notifications and user/admin state; uses Firebase Auth and checks the admin registry in Firestore.
- **Firebase client** — `src/lib/firebase.ts` — Initializes the browser Firebase app and exports Auth and Firestore clients.

##### API and grievance operations
- **Browser API and Firestore operations** — `src/services/api.ts` — Calls server AI endpoints and directly reads or updates Firestore grievance records, including status history, feedback and analytics inputs.
- **Express API and server runtime** — `server.ts` — Hosts API routes and development Vite integration; sampled routes perform AI operations and admin grievance management, with some routes acting on a server-side `complaints` collection.
- **Grievance domain types** — `src/types.ts` — Defines shared grievance, AI response, status and related data shapes used by the UI and API client.

##### External data and AI
- **Google Gemini** — *(external; null repository path)* Provides the documented AI classification and drafting capabilities; the server imports the Gemini SDK, and its AI routes call the provider.
- **Firebase Auth and Cloud Firestore** — *(external; null repository path)* Provide the documented identity and persistence platform; the browser client uses Auth and Firestore, and the context checks the `admins` collection.
- **Seed and civic reference data** — `src/data/seedData.ts` — Supplies typed department, officer, grievance, notification and audit-log records; the sampled excerpts identify grievance records as demo data.
- **Tamil Nadu assembly roster** — `src/data/tnAssembly2026.ts` — Holds a verified-seat snapshot with import-time integrity checks, supporting civic directory functionality.

#### Relationships

- **Browser user (Citizen) -> React bootstrap and screen router**: opens and interacts with the browser application.
- **React bootstrap and screen router -> Application context and authentication**: wraps the screen layout in the shared provider and reads its navigation and auth state.
- **React bootstrap and screen router -> Citizen filing and voice capture**: renders the filing screen for the file tab.
- **React bootstrap and screen router -> Citizen tracking and public information**: renders tracking and other public screens according to the active tab.
- **Admin user (Administrator) -> React bootstrap and screen router**: opens the admin tab; the app selects login or dashboard based on auth state.
- **Application context and authentication -> Firebase Auth and Cloud Firestore**: observes Auth state, creates anonymous sessions, and reads admin records; login and password-reset actions use Firebase Auth.
- **Application context and authentication -> Browser API and Firestore operations**: uses API operations for notification state changes.
- **Citizen filing and voice capture -> Browser API and Firestore operations**: requests complaint analysis and duplicate checking through the API client.
- **Browser API and Firestore operations -> Express API and server runtime**: sends HTTP requests to the documented AI endpoints.
- **Express API and server runtime -> Google Gemini**: invokes Gemini for AI analysis and resolution drafting where configured.
- **Express API and server runtime -> server-side complaints collection**: reads candidates for duplicate checks and looks up or updates records in sampled admin routes. This is server-held state, not evidence of a Firestore write.
- **Browser API and Firestore operations -> Firebase Auth and Cloud Firestore**: reads grievances and directly writes status changes and feedback using the browser Firestore SDK.
- **Browser API and Firestore operations -> Grievance domain types**: maps Firestore and HTTP results to shared domain shapes.
- **Seed and civic reference data -> React bootstrap and screen router**: supplies typed civic records used by application screens; exact consumption is not established from the sampled calls.
- **Tamil Nadu assembly roster -> React bootstrap and screen router**: supports the directory screen’s civic reference content; the sampled excerpt does not establish its import path.

#### Coverage limits

The source excerpts omit important portions of the form submission and server setup, so the exact submission endpoint, route guards, and full runtime wiring cannot be confirmed. README-described Firestore behavior and sampled server-side in-memory complaint operations do not establish one unified persistence path. The Supabase client exists in the tree, but no sampled call site establishes product use.

Main entry points: [`src/services/api.ts`](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/services/api.ts) (Browser API and Firestore), [`src/context/AppContext.tsx`](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/context/AppContext.tsx) (App context and auth), [`server.ts`](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/server.ts) (Express API), [`src/components/GrievanceForm.tsx`](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/components/GrievanceForm.tsx) (Filing and voice capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_app["React screen router<br/>Web app"]
  node_filing["Filing and voice capture<br/>UI"]
  node_tracking["Tracking and public screens<br/>UI"]
  node_context["App context and auth<br/>Shared state"]
end

subgraph group_operations["API and operations"]
  node_api["Browser API and Firestore<br/>Client service"]
  node_server["Express API<br/>Server"]
  node_complaints[("Server complaints<br/>In-memory collection")]
  node_types["Grievance domain types<br/>Shared types"]
end

subgraph group_external["External services"]
  node_gemini["Google Gemini<br/>AI provider"]
  node_firebase[("Firebase Auth and Firestore<br/>Identity and data platform")]
end

subgraph group_reference["Civic reference data"]
  node_seed["Seed and civic data<br/>Reference data"]
  node_roster["Assembly roster<br/>Reference data"]
end

node_citizen["Citizen<br/>External user"]
node_admin["Administrator<br/>External user"]

node_citizen -->|"uses"| node_app
node_app -->|"wraps and reads"| node_context
node_app -->|"renders"| node_filing
node_app -->|"renders"| node_tracking
node_admin -->|"uses"| node_app
node_context -->|"auth and admin lookup"| node_firebase
node_context -->|"updates notifications"| node_api
node_filing -->|"requests analysis"| node_api
node_api -->|"HTTP requests"| node_server
node_server -->|"invokes"| node_gemini
node_server -->|"reads and updates"| node_complaints
node_api -->|"reads and writes"| node_firebase
node_api -->|"maps results to"| node_types
node_seed -->|"supplies records"| node_app
node_roster -->|"supports directory"| node_app

click node_filing "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/components/GrievanceForm.tsx"
click node_tracking "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/components/CitizenTracker.tsx"
click node_context "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/context/AppContext.tsx"
click node_api "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/services/api.ts"
click node_server "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/server.ts"
click node_types "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/types.ts"
click node_seed "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/data/seedData.ts"
click node_roster "https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/data/tnAssembly2026.ts"

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,node_filing,node_tracking,node_context,node_citizen,node_admin toneBlue
class node_api,node_server,node_complaints,node_types toneAmber
class node_gemini,node_firebase toneMint
class node_seed,node_roster toneRose
```

## Components

### Browser app

- **React screen router**: Web app
- [Filing and voice capture](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/components/GrievanceForm.tsx): UI · `src/components/GrievanceForm.tsx`
- [Tracking and public screens](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/components/CitizenTracker.tsx): UI · `src/components/CitizenTracker.tsx`
- [App context and auth](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/context/AppContext.tsx): Shared state · `src/context/AppContext.tsx`

### API and operations

- [Browser API and Firestore](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/services/api.ts): Client service · `src/services/api.ts`
- [Express API](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/server.ts): Server · `server.ts`
- **Server complaints**: In-memory collection
- [Grievance domain types](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/types.ts): Shared types · `src/types.ts`

### External services

- **Google Gemini**: AI provider
- **Firebase Auth and Firestore**: Identity and data platform

### Civic reference data

- [Seed and civic data](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/data/seedData.ts): Reference data · `src/data/seedData.ts`
- [Assembly roster](https://github.com/leopears2008-cell/ai-powered-citizen-grievance-platform/blob/main/src/data/tnAssembly2026.ts): Reference data · `src/data/tnAssembly2026.ts`

### Other components

- **Citizen**: External user
- **Administrator**: External user

## Connections

- Citizen → React screen router: uses
- React screen router → App context and auth: wraps and reads
- React screen router → Filing and voice capture: renders
- React screen router → Tracking and public screens: renders
- Administrator → React screen router: uses
- App context and auth → Firebase Auth and Firestore: auth and admin lookup
- App context and auth → Browser API and Firestore: updates notifications
- Filing and voice capture → Browser API and Firestore: requests analysis
- Browser API and Firestore → Express API: HTTP requests
- Express API → Google Gemini: invokes
- Express API → Server complaints: reads and updates
- Browser API and Firestore → Firebase Auth and Firestore: reads and writes
- Browser API and Firestore → Grievance domain types: maps results to
- Seed and civic data → React screen router: supplies records
- Assembly roster → React screen router: supports directory