# srithineshs/unitedlocal architecture

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

- Interactive diagram: https://gitdiagram.com/srithineshs/unitedlocal
- Repository: https://github.com/srithineshs/unitedlocal

## Overview

UnitedLocal is a civic emergency-response and municipal-management platform serving citizens, responders, administrators, and volunteers. Its central workflow is a citizen SOS: capture location, create an incident, find and assign a nearby responder, notify the citizen, and track status. Separate capabilities cover evidence-backed complaint resolution, broadcasts, verified emergency contacts, volunteer tasks, and WhatsApp interaction. The graph combines documented product flows with source-visible calls; several API-to-service relationships and unsampled subsystem internals are not established by the excerpts and are therefore omitted.

Main entry points: [`lib/emergency/sos-service.ts`](https://github.com/srithineshs/unitedlocal/blob/main/lib/emergency/sos-service.ts) (Incident dispatch), [`lib/db/repository.ts`](https://github.com/srithineshs/unitedlocal/blob/main/lib/db/repository.ts) (Data repository), [`app/citizen/page.tsx`](https://github.com/srithineshs/unitedlocal/blob/main/app/citizen/page.tsx) (Citizen portal), [`lib/complaints/complaint-service.ts`](https://github.com/srithineshs/unitedlocal/blob/main/lib/complaints/complaint-service.ts) (Complaint handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["User portals"]
  node_citizen["Citizen portal<br/>[page.tsx]"]
  node_responder_consoles["Responder consoles<br/>[page.tsx]"]
  node_municipal_console["Municipal console<br/>[page.tsx]"]
  node_volunteer_portal["Volunteer portal<br/>[page.tsx]"]
  node_admin_console["Admin console<br/>[page.tsx]"]
end

subgraph group_emergency["Emergency response"]
  node_sos_ui["SOS capture"]
  node_sos_api["SOS API<br/>[route.ts]"]
  node_sos_service["Incident dispatch<br/>[sos-service.ts]"]
  node_nearest["Nearest responder"]
  node_distance["Distance calculation<br/>[haversine.ts]"]
  node_reverse_geo["Reverse geocoding<br/>[reverse-geocode.ts]"]
  node_tracking["Incident tracking<br/>[page.tsx]"]
end

subgraph group_municipal["Civic services"]
  node_complaint_ui["Complaint filing<br/>[ComplaintForm.tsx]"]
  node_complaint_service["Complaint handling"]
  node_complaint_api["Complaint API<br/>[route.ts]"]
  node_contacts["Emergency directory"]
  node_broadcast_api["Alert broadcasts<br/>[route.ts]"]
  node_volunteer_tasks["Volunteer tasks<br/>[route.ts]"]
end

subgraph group_communications["Communications"]
  node_whatsapp_webhook["WhatsApp webhook<br/>[route.ts]"]
  node_chatbot["WhatsApp chatbot<br/>[chatbot.ts]"]
  node_whatsapp_dispatch["WhatsApp notifications<br/>[index.ts]"]
  node_whatsapp_providers["Provider adapters<br/>[meta-cloud.ts]"]
end

subgraph group_platform["Shared platform"]
  node_auth["Session and roles<br/>[session.ts]"]
  node_role_rules["Role authorization<br/>[roles.ts]"]
  node_repository[("Data repository<br/>[repository.ts]")]
  node_audit["Audit logging<br/>[audit-logger.ts]"]
  node_map["GIS map<br/>[CivicMap.tsx]"]
end

node_citizen_actor(("Citizen"))
node_responders_actor(("Responders"))
node_whatsapp_service["WhatsApp Business"]
node_supabase[("Supabase")]

node_citizen_actor -->|"uses"| node_citizen
node_citizen -->|"opens SOS"| node_sos_ui
node_sos_ui -.->|"triggers"| node_sos_api
node_sos_api -.->|"handles"| node_sos_service
node_sos_service -->|"persists incident"| node_repository
node_sos_service -->|"finds unit"| node_nearest
node_sos_service -->|"resolves address"| node_reverse_geo
node_nearest -->|"measures distance"| node_distance
node_sos_service -->|"notifies citizen"| node_whatsapp_dispatch
node_sos_service -->|"records event"| node_audit
node_responders_actor -->|"uses"| node_responder_consoles
node_responder_consoles -->|"shows operations map"| node_map
node_citizen -->|"tracks incident"| node_tracking
node_citizen -->|"files complaint"| node_complaint_ui
node_complaint_ui -.->|"submits"| node_complaint_api
node_complaint_api -.->|"handles complaint"| node_complaint_service
node_municipal_console -->|"resolves with evidence"| node_complaint_service
node_complaint_service -->|"stores complaint"| node_repository
node_complaint_service -->|"records resolution"| node_audit
node_complaint_service -->|"sends updates"| node_whatsapp_dispatch
node_citizen -->|"views directory"| node_contacts
node_admin_console -->|"issues alerts"| node_broadcast_api
node_broadcast_api -->|"saves and fans out"| node_repository
node_broadcast_api -->|"records broadcast"| node_audit
node_volunteer_portal -->|"claims tasks"| node_volunteer_tasks
node_whatsapp_service -->|"sends messages"| node_whatsapp_webhook
node_whatsapp_webhook -.->|"processes messages"| node_chatbot
node_chatbot -.->|"stores sessions"| node_repository
node_whatsapp_dispatch -->|"selects provider"| node_whatsapp_providers
node_whatsapp_dispatch -->|"records delivery"| node_audit
node_whatsapp_providers -.->|"sends messages"| node_whatsapp_service
node_auth -->|"loads profiles"| node_repository
node_auth -.->|"validates roles"| node_role_rules
node_repository -.->|"stores platform data"| node_supabase

click node_citizen "https://github.com/srithineshs/unitedlocal/blob/main/app/citizen/page.tsx"
click node_responder_consoles "https://github.com/srithineshs/unitedlocal/blob/main/app/police/page.tsx"
click node_municipal_console "https://github.com/srithineshs/unitedlocal/blob/main/app/municipal/page.tsx"
click node_volunteer_portal "https://github.com/srithineshs/unitedlocal/blob/main/app/volunteer/page.tsx"
click node_admin_console "https://github.com/srithineshs/unitedlocal/blob/main/app/admin/page.tsx"
click node_sos_ui "https://github.com/srithineshs/unitedlocal/blob/main/components/emergency/SOSTriggerButton.tsx"
click node_sos_api "https://github.com/srithineshs/unitedlocal/blob/main/app/api/sos/trigger/route.ts"
click node_sos_service "https://github.com/srithineshs/unitedlocal/blob/main/lib/emergency/sos-service.ts"
click node_nearest "https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/nearest-responder.ts"
click node_distance "https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/haversine.ts"
click node_reverse_geo "https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/reverse-geocode.ts"
click node_tracking "https://github.com/srithineshs/unitedlocal/blob/main/app/citizen/track/page.tsx"
click node_complaint_ui "https://github.com/srithineshs/unitedlocal/blob/main/components/complaints/ComplaintForm.tsx"
click node_complaint_service "https://github.com/srithineshs/unitedlocal/blob/main/lib/complaints/complaint-service.ts"
click node_complaint_api "https://github.com/srithineshs/unitedlocal/blob/main/app/api/complaints/route.ts"
click node_contacts "https://github.com/srithineshs/unitedlocal/blob/main/components/emergency/EmergencyContactsGrid.tsx"
click node_broadcast_api "https://github.com/srithineshs/unitedlocal/blob/main/app/api/broadcasts/route.ts"
click node_volunteer_tasks "https://github.com/srithineshs/unitedlocal/blob/main/app/api/volunteers/tasks/route.ts"
click node_whatsapp_webhook "https://github.com/srithineshs/unitedlocal/blob/main/app/api/whatsapp/webhook/route.ts"
click node_chatbot "https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/chatbot.ts"
click node_whatsapp_dispatch "https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/index.ts"
click node_whatsapp_providers "https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/meta-cloud.ts"
click node_auth "https://github.com/srithineshs/unitedlocal/blob/main/lib/auth/session.ts"
click node_role_rules "https://github.com/srithineshs/unitedlocal/blob/main/lib/auth/roles.ts"
click node_repository "https://github.com/srithineshs/unitedlocal/blob/main/lib/db/repository.ts"
click node_audit "https://github.com/srithineshs/unitedlocal/blob/main/lib/audit/audit-logger.ts"
click node_map "https://github.com/srithineshs/unitedlocal/blob/main/components/maps/CivicMap.tsx"

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_citizen,node_responder_consoles,node_municipal_console,node_volunteer_portal,node_admin_console toneBlue
class node_sos_ui,node_sos_api,node_sos_service,node_nearest,node_distance,node_reverse_geo,node_tracking,node_supabase toneAmber
class node_complaint_ui,node_complaint_service,node_complaint_api,node_contacts,node_broadcast_api,node_volunteer_tasks toneMint
class node_whatsapp_webhook,node_chatbot,node_whatsapp_dispatch,node_whatsapp_providers toneRose
class node_auth,node_role_rules,node_repository,node_audit,node_map,node_citizen_actor,node_responders_actor,node_whatsapp_service toneIndigo
```

## Components

### User portals

- [Citizen portal](https://github.com/srithineshs/unitedlocal/blob/main/app/citizen/page.tsx): `app/citizen/page.tsx`
- [Responder consoles](https://github.com/srithineshs/unitedlocal/blob/main/app/police/page.tsx): `app/police/page.tsx`
- [Municipal console](https://github.com/srithineshs/unitedlocal/blob/main/app/municipal/page.tsx): `app/municipal/page.tsx`
- [Volunteer portal](https://github.com/srithineshs/unitedlocal/blob/main/app/volunteer/page.tsx): `app/volunteer/page.tsx`
- [Admin console](https://github.com/srithineshs/unitedlocal/blob/main/app/admin/page.tsx): `app/admin/page.tsx`

### Emergency response

- [SOS capture](https://github.com/srithineshs/unitedlocal/blob/main/components/emergency/SOSTriggerButton.tsx): `components/emergency/SOSTriggerButton.tsx`
- [SOS API](https://github.com/srithineshs/unitedlocal/blob/main/app/api/sos/trigger/route.ts): `app/api/sos/trigger/route.ts`
- [Incident dispatch](https://github.com/srithineshs/unitedlocal/blob/main/lib/emergency/sos-service.ts): `lib/emergency/sos-service.ts`
- [Nearest responder](https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/nearest-responder.ts): `lib/geo/nearest-responder.ts`
- [Distance calculation](https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/haversine.ts): `lib/geo/haversine.ts`
- [Reverse geocoding](https://github.com/srithineshs/unitedlocal/blob/main/lib/geo/reverse-geocode.ts): `lib/geo/reverse-geocode.ts`
- [Incident tracking](https://github.com/srithineshs/unitedlocal/blob/main/app/citizen/track/page.tsx): `app/citizen/track/page.tsx`

### Civic services

- [Complaint filing](https://github.com/srithineshs/unitedlocal/blob/main/components/complaints/ComplaintForm.tsx): `components/complaints/ComplaintForm.tsx`
- [Complaint handling](https://github.com/srithineshs/unitedlocal/blob/main/lib/complaints/complaint-service.ts): `lib/complaints/complaint-service.ts`
- [Complaint API](https://github.com/srithineshs/unitedlocal/blob/main/app/api/complaints/route.ts): `app/api/complaints/route.ts`
- [Emergency directory](https://github.com/srithineshs/unitedlocal/blob/main/components/emergency/EmergencyContactsGrid.tsx): `components/emergency/EmergencyContactsGrid.tsx`
- [Alert broadcasts](https://github.com/srithineshs/unitedlocal/blob/main/app/api/broadcasts/route.ts): `app/api/broadcasts/route.ts`
- [Volunteer tasks](https://github.com/srithineshs/unitedlocal/blob/main/app/api/volunteers/tasks/route.ts): `app/api/volunteers/tasks/route.ts`

### Communications

- [WhatsApp webhook](https://github.com/srithineshs/unitedlocal/blob/main/app/api/whatsapp/webhook/route.ts): `app/api/whatsapp/webhook/route.ts`
- [WhatsApp chatbot](https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/chatbot.ts): `lib/whatsapp/chatbot.ts`
- [WhatsApp notifications](https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/index.ts): `lib/whatsapp/index.ts`
- [Provider adapters](https://github.com/srithineshs/unitedlocal/blob/main/lib/whatsapp/meta-cloud.ts): `lib/whatsapp/meta-cloud.ts`

### Shared platform

- [Session and roles](https://github.com/srithineshs/unitedlocal/blob/main/lib/auth/session.ts): `lib/auth/session.ts`
- [Role authorization](https://github.com/srithineshs/unitedlocal/blob/main/lib/auth/roles.ts): `lib/auth/roles.ts`
- [Data repository](https://github.com/srithineshs/unitedlocal/blob/main/lib/db/repository.ts): `lib/db/repository.ts`
- [Audit logging](https://github.com/srithineshs/unitedlocal/blob/main/lib/audit/audit-logger.ts): `lib/audit/audit-logger.ts`
- [GIS map](https://github.com/srithineshs/unitedlocal/blob/main/components/maps/CivicMap.tsx): `components/maps/CivicMap.tsx`

### Other components

- **Citizen**
- **Responders**
- **WhatsApp Business**
- **Supabase**

## Connections

- Citizen → Citizen portal: uses (evidence: `README.md`)
- Citizen portal → SOS capture: opens SOS (evidence: `README.md`)
- SOS capture → SOS API: triggers
- SOS API → Incident dispatch: handles
- Incident dispatch → Data repository: persists incident (evidence: `lib/emergency/sos-service.ts`)
- Incident dispatch → Nearest responder: finds unit (evidence: `lib/emergency/sos-service.ts`)
- Incident dispatch → Reverse geocoding: resolves address (evidence: `lib/emergency/sos-service.ts`)
- Nearest responder → Distance calculation: measures distance (evidence: `lib/geo/nearest-responder.ts`)
- Incident dispatch → WhatsApp notifications: notifies citizen (evidence: `lib/emergency/sos-service.ts`)
- Incident dispatch → Audit logging: records event (evidence: `lib/emergency/sos-service.ts`)
- Responders → Responder consoles: uses (evidence: `README.md`)
- Responder consoles → GIS map: shows operations map (evidence: `app/police/page.tsx`)
- Citizen portal → Incident tracking: tracks incident (evidence: `README.md`)
- Citizen portal → Complaint filing: files complaint (evidence: `README.md`)
- Complaint filing → Complaint API: submits
- Complaint API → Complaint handling: handles complaint
- Municipal console → Complaint handling: resolves with evidence (evidence: `README.md`)
- Complaint handling → Data repository: stores complaint (evidence: `lib/complaints/complaint-service.ts`)
- Complaint handling → Audit logging: records resolution (evidence: `lib/complaints/complaint-service.ts`)
- Complaint handling → WhatsApp notifications: sends updates (evidence: `lib/complaints/complaint-service.ts`)
- Citizen portal → Emergency directory: views directory (evidence: `README.md`)
- Admin console → Alert broadcasts: issues alerts (evidence: `README.md`)
- Alert broadcasts → Data repository: saves and fans out (evidence: `app/api/broadcasts/route.ts`)
- Alert broadcasts → Audit logging: records broadcast (evidence: `app/api/broadcasts/route.ts`)
- Volunteer portal → Volunteer tasks: claims tasks (evidence: `README.md`)
- WhatsApp Business → WhatsApp webhook: sends messages (evidence: `README.md`)
- WhatsApp webhook → WhatsApp chatbot: processes messages
- WhatsApp chatbot → Data repository: stores sessions
- WhatsApp notifications → Provider adapters: selects provider (evidence: `lib/whatsapp/index.ts`)
- WhatsApp notifications → Audit logging: records delivery (evidence: `lib/whatsapp/index.ts`)
- Provider adapters → WhatsApp Business: sends messages
- Session and roles → Data repository: loads profiles (evidence: `lib/auth/session.ts`)
- Session and roles → Role authorization: validates roles
- Data repository → Supabase: stores platform data (evidence: `README.md`)
