# meethjain09/civicresolve architecture

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

- Interactive diagram: https://gitdiagram.com/meethjain09/civicresolve
- Repository: https://github.com/meethjain09/civicresolve

## Overview

CivicResolve is a role-based municipal grievance platform. Citizens submit reports with photos and location details; the server validates and persists them immediately, then runs Gemini triage asynchronously to classify, prioritize, and route each ticket. Citizens track progress, department resolvers update status and request reassignment, and administrators manage complaints and staff. The graph combines sampled calls and imports with README-documented capabilities; unsampled client/API wiring and reverse-geocoding provider details are shown only where documented.

Main entry points: [`src/app/api/complaints/route.ts`](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/complaints/route.ts) (Complaint submission), [`src/lib/supabase/server.ts`](https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/server.ts) (Server authentication), [`src/lib/supabase/admin.ts`](https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/admin.ts) (Privileged data client), [`src/lib/gemini/triage.ts`](https://github.com/meethjain09/civicresolve/blob/main/src/lib/gemini/triage.ts) (Multimodal AI triage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Role workspaces"]
  node_authui["Sign-in and demo<br/>[AuthForm.tsx]"]
  node_citizenui["Report and track"]
  node_complaintform["Complaint form<br/>[ComplaintForm.tsx]"]
  node_location["Location picker<br/>[LocationPicker.tsx]"]
  node_resolverui["Resolver workspace"]
  node_resolverticket["Resolver ticket actions"]
  node_adminui["Admin workspace"]
  node_admincomplaints["Complaint administration"]
  node_staff["Staff directory<br/>[StaffManager.tsx]"]
end

subgraph group_api["Application API"]
  node_submission["Complaint submission<br/>[route.ts]"]
  node_resolverapi["Resolver updates<br/>[route.ts]"]
  node_adminapi["Admin complaint actions<br/>[route.ts]"]
  node_retryapi["Retry AI triage<br/>[route.ts]"]
  node_staffapi["Resolver provisioning<br/>[route.ts]"]
  node_geocodeapi["Reverse geocoding<br/>[route.ts]"]
end

subgraph group_domain["Triage and validation"]
  node_validation["Complaint validation<br/>[complaints.ts]"]
  node_triage["Multimodal AI triage<br/>[triage.ts]"]
end

subgraph group_data["Identity and persistence"]
  node_serverauth["Server authentication<br/>[server.ts]"]
  node_adminclient["Privileged data client<br/>[admin.ts]"]
end

subgraph group_integrations["External services"]
  node_store[("Supabase database and storage")]
  node_gemini{{"Google Gemini"}}
  node_geocoders{{"Nominatim and BigDataCloud"}}
end

node_citizens(("Citizens"))
node_resolvers(("Department resolvers"))
node_admins(("Municipal administrators"))

node_citizens -->|"sign in"| node_authui
node_resolvers -->|"sign in"| node_authui
node_admins -->|"sign in"| node_authui
node_citizens -->|"report and track"| node_citizenui
node_citizenui -->|"renders"| node_complaintform
node_complaintform -->|"uses"| node_location
node_complaintform -->|"submits report"| node_submission
node_resolvers -->|"manage assigned tickets"| node_resolverui
node_resolverui -->|"renders"| node_resolverticket
node_resolverticket -->|"updates ticket"| node_resolverapi
node_admins -->|"manage platform"| node_adminui
node_adminui -->|"renders"| node_admincomplaints
node_adminui -->|"renders"| node_staff
node_admincomplaints -->|"manages tickets"| node_adminapi
node_admincomplaints -->|"retries triage"| node_retryapi
node_staff -->|"provisions resolvers"| node_staffapi
node_submission -->|"authenticates user"| node_serverauth
node_submission -->|"validates payload"| node_validation
node_submission -->|"persists complaint"| node_adminclient
node_submission -->|"schedules analysis"| node_triage
node_triage -->|"analyzes evidence"| node_gemini
node_submission -->|"inserts report"| node_store
node_triage -->|"updates triage"| node_store
node_resolverapi -->|"authenticates user"| node_serverauth
node_resolverapi -->|"updates ticket"| node_adminclient
node_adminapi -->|"authenticates user"| node_serverauth
node_adminapi -->|"administers records"| node_adminclient
node_retryapi -->|"invokes triage"| node_triage
node_retryapi -->|"updates records"| node_adminclient
node_staffapi -->|"manages accounts"| node_adminclient
node_geocodeapi -->|"authenticates request"| node_serverauth
node_location -->|"requests address lookup"| node_geocodeapi
node_geocodeapi -->|"reverse geocodes"| node_geocoders
node_authui -->|"uses session"| node_serverauth
node_serverauth -->|"reads identity"| node_store
node_adminclient -->|"uses service role"| node_store

click node_authui "https://github.com/meethjain09/civicresolve/blob/main/src/components/auth/AuthForm.tsx"
click node_citizenui "https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/CitizenDashboardClient.tsx"
click node_complaintform "https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/ComplaintForm.tsx"
click node_location "https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/LocationPicker.tsx"
click node_resolverui "https://github.com/meethjain09/civicresolve/blob/main/src/components/resolver/ResolverDashboardClient.tsx"
click node_resolverticket "https://github.com/meethjain09/civicresolve/blob/main/src/components/resolver/ResolverTicketCard.tsx"
click node_adminui "https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/AdminDashboardClient.tsx"
click node_admincomplaints "https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/AdminComplaintCenter.tsx"
click node_staff "https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/StaffManager.tsx"
click node_submission "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/complaints/route.ts"
click node_resolverapi "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/resolver/complaints/%5Bid%5D/route.ts"
click node_adminapi "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/complaints/%5Bid%5D/route.ts"
click node_retryapi "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/retry-ai/route.ts"
click node_staffapi "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/resolvers/route.ts"
click node_geocodeapi "https://github.com/meethjain09/civicresolve/blob/main/src/app/api/geocode/reverse/route.ts"
click node_validation "https://github.com/meethjain09/civicresolve/blob/main/src/lib/validation/complaints.ts"
click node_triage "https://github.com/meethjain09/civicresolve/blob/main/src/lib/gemini/triage.ts"
click node_serverauth "https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/server.ts"
click node_adminclient "https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/admin.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_authui,node_citizenui,node_complaintform,node_location,node_resolverui,node_resolverticket,node_adminui,node_admincomplaints,node_staff toneBlue
class node_submission,node_resolverapi,node_adminapi,node_retryapi,node_staffapi,node_geocodeapi toneAmber
class node_validation,node_triage toneMint
class node_serverauth,node_adminclient toneRose
class node_store,node_gemini,node_geocoders,node_citizens,node_resolvers,node_admins toneIndigo
```

## Components

### Role workspaces

- [Sign-in and demo](https://github.com/meethjain09/civicresolve/blob/main/src/components/auth/AuthForm.tsx): `src/components/auth/AuthForm.tsx`
- [Report and track](https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/CitizenDashboardClient.tsx): `src/components/citizen/CitizenDashboardClient.tsx`
- [Complaint form](https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/ComplaintForm.tsx): `src/components/citizen/ComplaintForm.tsx`
- [Location picker](https://github.com/meethjain09/civicresolve/blob/main/src/components/citizen/LocationPicker.tsx): `src/components/citizen/LocationPicker.tsx`
- [Resolver workspace](https://github.com/meethjain09/civicresolve/blob/main/src/components/resolver/ResolverDashboardClient.tsx): `src/components/resolver/ResolverDashboardClient.tsx`
- [Resolver ticket actions](https://github.com/meethjain09/civicresolve/blob/main/src/components/resolver/ResolverTicketCard.tsx): `src/components/resolver/ResolverTicketCard.tsx`
- [Admin workspace](https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/AdminDashboardClient.tsx): `src/components/admin/AdminDashboardClient.tsx`
- [Complaint administration](https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/AdminComplaintCenter.tsx): `src/components/admin/AdminComplaintCenter.tsx`
- [Staff directory](https://github.com/meethjain09/civicresolve/blob/main/src/components/admin/StaffManager.tsx): `src/components/admin/StaffManager.tsx`

### Application API

- [Complaint submission](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/complaints/route.ts): `src/app/api/complaints/route.ts`
- [Resolver updates](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/resolver/complaints/%5Bid%5D/route.ts): `src/app/api/resolver/complaints/[id]/route.ts`
- [Admin complaint actions](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/complaints/%5Bid%5D/route.ts): `src/app/api/admin/complaints/[id]/route.ts`
- [Retry AI triage](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/retry-ai/route.ts): `src/app/api/admin/retry-ai/route.ts`
- [Resolver provisioning](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/admin/resolvers/route.ts): `src/app/api/admin/resolvers/route.ts`
- [Reverse geocoding](https://github.com/meethjain09/civicresolve/blob/main/src/app/api/geocode/reverse/route.ts): `src/app/api/geocode/reverse/route.ts`

### Triage and validation

- [Complaint validation](https://github.com/meethjain09/civicresolve/blob/main/src/lib/validation/complaints.ts): `src/lib/validation/complaints.ts`
- [Multimodal AI triage](https://github.com/meethjain09/civicresolve/blob/main/src/lib/gemini/triage.ts): `src/lib/gemini/triage.ts`

### Identity and persistence

- [Server authentication](https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Privileged data client](https://github.com/meethjain09/civicresolve/blob/main/src/lib/supabase/admin.ts): `src/lib/supabase/admin.ts`

### External services

- **Supabase database and storage**
- **Google Gemini**
- **Nominatim and BigDataCloud**

### Other components

- **Citizens**
- **Department resolvers**
- **Municipal administrators**

## Connections

- Citizens → Sign-in and demo: sign in (evidence: `README.md`)
- Department resolvers → Sign-in and demo: sign in (evidence: `README.md`)
- Municipal administrators → Sign-in and demo: sign in (evidence: `README.md`)
- Citizens → Report and track: report and track (evidence: `README.md`)
- Report and track → Complaint form: renders (evidence: `src/components/citizen/CitizenDashboardClient.tsx`)
- Complaint form → Location picker: uses (evidence: `src/components/citizen/ComplaintForm.tsx`)
- Complaint form → Complaint submission: submits report (evidence: `README.md`)
- Department resolvers → Resolver workspace: manage assigned tickets (evidence: `README.md`)
- Resolver workspace → Resolver ticket actions: renders (evidence: `src/components/resolver/ResolverDashboardClient.tsx`)
- Resolver ticket actions → Resolver updates: updates ticket (evidence: `README.md`)
- Municipal administrators → Admin workspace: manage platform (evidence: `README.md`)
- Admin workspace → Complaint administration: renders (evidence: `src/components/admin/AdminDashboardClient.tsx`)
- Admin workspace → Staff directory: renders (evidence: `src/components/admin/AdminDashboardClient.tsx`)
- Complaint administration → Admin complaint actions: manages tickets (evidence: `README.md`)
- Complaint administration → Retry AI triage: retries triage (evidence: `README.md`)
- Staff directory → Resolver provisioning: provisions resolvers (evidence: `README.md`)
- Complaint submission → Server authentication: authenticates user (evidence: `src/app/api/complaints/route.ts`)
- Complaint submission → Complaint validation: validates payload (evidence: `src/app/api/complaints/route.ts`)
- Complaint submission → Privileged data client: persists complaint (evidence: `src/app/api/complaints/route.ts`)
- Complaint submission → Multimodal AI triage: schedules analysis (evidence: `src/app/api/complaints/route.ts`)
- Multimodal AI triage → Google Gemini: analyzes evidence (evidence: `README.md`)
- Complaint submission → Supabase database and storage: inserts report (evidence: `README.md`)
- Multimodal AI triage → Supabase database and storage: updates triage (evidence: `README.md`)
- Resolver updates → Server authentication: authenticates user (evidence: `src/app/api/resolver/complaints/[id]/route.ts`)
- Resolver updates → Privileged data client: updates ticket (evidence: `src/app/api/resolver/complaints/[id]/route.ts`)
- Admin complaint actions → Server authentication: authenticates user (evidence: `src/app/api/admin/complaints/[id]/route.ts`)
- Admin complaint actions → Privileged data client: administers records (evidence: `src/app/api/admin/complaints/[id]/route.ts`)
- Retry AI triage → Multimodal AI triage: invokes triage (evidence: `src/app/api/admin/retry-ai/route.ts`)
- Retry AI triage → Privileged data client: updates records (evidence: `src/app/api/admin/retry-ai/route.ts`)
- Resolver provisioning → Privileged data client: manages accounts (evidence: `src/app/api/admin/resolvers/route.ts`)
- Reverse geocoding → Server authentication: authenticates request (evidence: `src/app/api/geocode/reverse/route.ts`)
- Location picker → Reverse geocoding: requests address lookup (evidence: `README.md`)
- Reverse geocoding → Nominatim and BigDataCloud: reverse geocodes (evidence: `README.md`)
- Sign-in and demo → Server authentication: uses session (evidence: `src/components/auth/AuthForm.tsx`)
- Server authentication → Supabase database and storage: reads identity (evidence: `README.md`)
- Privileged data client → Supabase database and storage: uses service role (evidence: `src/lib/supabase/admin.ts`)
