# prosofproest/civicflow architecture

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

- Interactive diagram: https://gitdiagram.com/prosofproest/civicflow
- Repository: https://github.com/prosofproest/civicflow

## Overview

CivicFlow is a civic complaint intake and municipal triage/resolution platform. Citizens submit location-aware reports, which are stored and processed with AI assistance and deterministic priority, duplicate, and hotspot analysis; citizens and municipal staff then view status and take action. The README documents Firebase/Firestore authentication and persistence, optional Cloudinary image uploads, and Groq with deterministic fallback. Several screens and service implementations were not sampled, so their documented capabilities are shown without asserting unsampled call chains.

Main entry points: [`src/lib/services/complaints.ts`](https://github.com/prosofproest/civicflow/blob/main/src/lib/services/complaints.ts) (Complaint services), [`src/lib/assistant/service.ts`](https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/service.ts) (Assistant orchestration), [`src/app/api/assistant/chat/route.ts`](https://github.com/prosofproest/civicflow/blob/main/src/app/api/assistant/chat/route.ts) (Assistant chat API), [`src/app/api/complaints/route.ts`](https://github.com/prosofproest/civicflow/blob/main/src/app/api/complaints/route.ts) (Complaint API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Citizen Intake"]
  node_intake["Report submission<br/>[page.tsx]"]
  node_citizen_portal["Citizen portal<br/>[page.tsx]"]
  node_assistant_ui["Civic assistant<br/>[CivicAssistant.tsx]"]
end

subgraph group_identity["Identity &amp; Access"]
  node_auth_ui["Client authentication<br/>[auth-context.tsx]"]
  node_firebase_client["Firebase client auth<br/>[client.ts]"]
  node_session_api["Session establishment<br/>[route.ts]"]
  node_server_session["Server session checks<br/>[server-session.ts]"]
  node_admin_auth["Firebase Admin<br/>[admin.ts]"]
end

subgraph group_understand["Analysis &amp; Assistance"]
  node_priority["Priority scoring<br/>[priority.ts]"]
  node_duplicates["Duplicate detection<br/>[duplicate.ts]"]
  node_hotspots["Hotspot clustering<br/>[hotspot.ts]"]
  node_map["Spatial map<br/>[ComplaintMap.tsx]"]
  node_chat_api["Assistant chat API<br/>[route.ts]"]
  node_assistant_service["Assistant orchestration<br/>[service.ts]"]
  node_assistant_fallback["Rule-based fallback<br/>[fallback.ts]"]
  node_system_prompt["Assistant prompt<br/>[system-prompt.ts]"]
end

subgraph group_operations["Complaint Operations"]
  node_complaint_api["Complaint API<br/>[route.ts]"]
  node_complaint_detail_api["Complaint updates<br/>[route.ts]"]
  node_complaint_service["Complaint services<br/>[complaints.ts]"]
  node_officer_console["Officer workflow<br/>[page.tsx]"]
  node_admin_console["Admin overview<br/>[page.tsx]"]
end

subgraph group_platform["Persistence &amp; Integrations"]
  node_groq["Groq inference<br/>[groq.ts]"]
  node_firestore[("Cloud Firestore")]
  node_cloudinary_api["Upload signing API<br/>[route.ts]"]
end

node_citizen(("Citizen"))
node_staff(("Municipal staff"))
node_cloudinary["Cloudinary"]

node_citizen -->|"submits report"| node_intake
node_intake -.->|"sends submission"| node_complaint_api
node_citizen -->|"tracks reports"| node_citizen_portal
node_staff -->|"manages cases"| node_officer_console
node_staff -->|"reviews metrics"| node_admin_console
node_auth_ui -->|"uses auth"| node_firebase_client
node_auth_ui -->|"syncs session"| node_session_api
node_session_api -->|"verifies token"| node_admin_auth
node_complaint_api -->|"checks session"| node_server_session
node_complaint_api -->|"creates or lists"| node_complaint_service
node_complaint_detail_api -->|"reads or updates"| node_complaint_service
node_complaint_service -.->|"persists complaints"| node_firestore
node_citizen -->|"asks questions"| node_assistant_ui
node_assistant_ui -.->|"sends chat"| node_chat_api
node_chat_api -->|"checks session"| node_server_session
node_chat_api -->|"processes chat"| node_assistant_service
node_assistant_service -->|"looks up complaints"| node_complaint_service
node_assistant_service -->|"builds prompt"| node_system_prompt
node_assistant_service -->|"falls back to"| node_assistant_fallback
node_assistant_service -.->|"requests inference"| node_groq
node_complaint_service -.->|"scores reports"| node_priority
node_complaint_service -.->|"checks duplicates"| node_duplicates
node_complaint_service -.->|"clusters reports"| node_hotspots
node_staff -->|"inspects geography"| node_map
node_cloudinary_api -->|"checks session"| node_server_session
node_cloudinary_api -.->|"signs uploads"| node_cloudinary

click node_intake "https://github.com/prosofproest/civicflow/blob/main/src/app/citizen/submit/page.tsx"
click node_citizen_portal "https://github.com/prosofproest/civicflow/blob/main/src/app/citizen/complaints/page.tsx"
click node_assistant_ui "https://github.com/prosofproest/civicflow/blob/main/src/components/assistant/CivicAssistant.tsx"
click node_auth_ui "https://github.com/prosofproest/civicflow/blob/main/src/lib/auth/auth-context.tsx"
click node_firebase_client "https://github.com/prosofproest/civicflow/blob/main/src/lib/firebase/client.ts"
click node_session_api "https://github.com/prosofproest/civicflow/blob/main/src/app/api/auth/session/route.ts"
click node_server_session "https://github.com/prosofproest/civicflow/blob/main/src/lib/auth/server-session.ts"
click node_admin_auth "https://github.com/prosofproest/civicflow/blob/main/src/lib/firebase/admin.ts"
click node_complaint_api "https://github.com/prosofproest/civicflow/blob/main/src/app/api/complaints/route.ts"
click node_complaint_detail_api "https://github.com/prosofproest/civicflow/blob/main/src/app/api/complaints/%5Bid%5D/route.ts"
click node_complaint_service "https://github.com/prosofproest/civicflow/blob/main/src/lib/services/complaints.ts"
click node_officer_console "https://github.com/prosofproest/civicflow/blob/main/src/app/officer/page.tsx"
click node_admin_console "https://github.com/prosofproest/civicflow/blob/main/src/app/admin/page.tsx"
click node_priority "https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/priority.ts"
click node_duplicates "https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/duplicate.ts"
click node_hotspots "https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/hotspot.ts"
click node_map "https://github.com/prosofproest/civicflow/blob/main/src/components/map/ComplaintMap.tsx"
click node_chat_api "https://github.com/prosofproest/civicflow/blob/main/src/app/api/assistant/chat/route.ts"
click node_assistant_service "https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/service.ts"
click node_assistant_fallback "https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/fallback.ts"
click node_system_prompt "https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/system-prompt.ts"
click node_groq "https://github.com/prosofproest/civicflow/blob/main/src/lib/ai/groq.ts"
click node_cloudinary_api "https://github.com/prosofproest/civicflow/blob/main/src/app/api/upload/signature/route.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_intake,node_citizen_portal,node_assistant_ui toneBlue
class node_auth_ui,node_firebase_client,node_session_api,node_server_session,node_admin_auth toneAmber
class node_priority,node_duplicates,node_hotspots,node_map,node_chat_api,node_assistant_service,node_assistant_fallback,node_system_prompt toneMint
class node_complaint_api,node_complaint_detail_api,node_complaint_service,node_officer_console,node_admin_console toneRose
class node_groq,node_firestore,node_cloudinary_api,node_citizen,node_staff,node_cloudinary toneIndigo
```

## Components

### Citizen Intake

- [Report submission](https://github.com/prosofproest/civicflow/blob/main/src/app/citizen/submit/page.tsx): `src/app/citizen/submit/page.tsx`
- [Citizen portal](https://github.com/prosofproest/civicflow/blob/main/src/app/citizen/complaints/page.tsx): `src/app/citizen/complaints/page.tsx`
- [Civic assistant](https://github.com/prosofproest/civicflow/blob/main/src/components/assistant/CivicAssistant.tsx): `src/components/assistant/CivicAssistant.tsx`

### Identity & Access

- [Client authentication](https://github.com/prosofproest/civicflow/blob/main/src/lib/auth/auth-context.tsx): `src/lib/auth/auth-context.tsx`
- [Firebase client auth](https://github.com/prosofproest/civicflow/blob/main/src/lib/firebase/client.ts): `src/lib/firebase/client.ts`
- [Session establishment](https://github.com/prosofproest/civicflow/blob/main/src/app/api/auth/session/route.ts): `src/app/api/auth/session/route.ts`
- [Server session checks](https://github.com/prosofproest/civicflow/blob/main/src/lib/auth/server-session.ts): `src/lib/auth/server-session.ts`
- [Firebase Admin](https://github.com/prosofproest/civicflow/blob/main/src/lib/firebase/admin.ts): `src/lib/firebase/admin.ts`

### Analysis & Assistance

- [Priority scoring](https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/priority.ts): `src/lib/engine/priority.ts`
- [Duplicate detection](https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/duplicate.ts): `src/lib/engine/duplicate.ts`
- [Hotspot clustering](https://github.com/prosofproest/civicflow/blob/main/src/lib/engine/hotspot.ts): `src/lib/engine/hotspot.ts`
- [Spatial map](https://github.com/prosofproest/civicflow/blob/main/src/components/map/ComplaintMap.tsx): `src/components/map/ComplaintMap.tsx`
- [Assistant chat API](https://github.com/prosofproest/civicflow/blob/main/src/app/api/assistant/chat/route.ts): `src/app/api/assistant/chat/route.ts`
- [Assistant orchestration](https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/service.ts): `src/lib/assistant/service.ts`
- [Rule-based fallback](https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/fallback.ts): `src/lib/assistant/fallback.ts`
- [Assistant prompt](https://github.com/prosofproest/civicflow/blob/main/src/lib/assistant/system-prompt.ts): `src/lib/assistant/system-prompt.ts`

### Complaint Operations

- [Complaint API](https://github.com/prosofproest/civicflow/blob/main/src/app/api/complaints/route.ts): `src/app/api/complaints/route.ts`
- [Complaint updates](https://github.com/prosofproest/civicflow/blob/main/src/app/api/complaints/%5Bid%5D/route.ts): `src/app/api/complaints/[id]/route.ts`
- [Complaint services](https://github.com/prosofproest/civicflow/blob/main/src/lib/services/complaints.ts): `src/lib/services/complaints.ts`
- [Officer workflow](https://github.com/prosofproest/civicflow/blob/main/src/app/officer/page.tsx): `src/app/officer/page.tsx`
- [Admin overview](https://github.com/prosofproest/civicflow/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`

### Persistence & Integrations

- [Groq inference](https://github.com/prosofproest/civicflow/blob/main/src/lib/ai/groq.ts): `src/lib/ai/groq.ts`
- **Cloud Firestore**
- [Upload signing API](https://github.com/prosofproest/civicflow/blob/main/src/app/api/upload/signature/route.ts): `src/app/api/upload/signature/route.ts`

### Other components

- **Citizen**
- **Municipal staff**
- **Cloudinary**

## Connections

- Citizen → Report submission: submits report (evidence: `README.md`)
- Report submission → Complaint API: sends submission
- Citizen → Citizen portal: tracks reports (evidence: `README.md`)
- Municipal staff → Officer workflow: manages cases (evidence: `README.md`)
- Municipal staff → Admin overview: reviews metrics (evidence: `README.md`)
- Client authentication → Firebase client auth: uses auth (evidence: `src/lib/auth/auth-context.tsx`)
- Client authentication → Session establishment: syncs session (evidence: `src/lib/auth/auth-context.tsx`)
- Session establishment → Firebase Admin: verifies token (evidence: `src/app/api/auth/session/route.ts`)
- Complaint API → Server session checks: checks session (evidence: `src/app/api/complaints/route.ts`)
- Complaint API → Complaint services: creates or lists (evidence: `src/app/api/complaints/route.ts`)
- Complaint updates → Complaint services: reads or updates (evidence: `src/app/api/complaints/[id]/route.ts`)
- Complaint services → Cloud Firestore: persists complaints
- Citizen → Civic assistant: asks questions (evidence: `README.md`)
- Civic assistant → Assistant chat API: sends chat
- Assistant chat API → Server session checks: checks session (evidence: `src/app/api/assistant/chat/route.ts`)
- Assistant chat API → Assistant orchestration: processes chat (evidence: `src/app/api/assistant/chat/route.ts`)
- Assistant orchestration → Complaint services: looks up complaints (evidence: `src/lib/assistant/service.ts`)
- Assistant orchestration → Assistant prompt: builds prompt (evidence: `src/lib/assistant/service.ts`)
- Assistant orchestration → Rule-based fallback: falls back to (evidence: `src/lib/assistant/service.ts`)
- Assistant orchestration → Groq inference: requests inference
- Complaint services → Priority scoring: scores reports
- Complaint services → Duplicate detection: checks duplicates
- Complaint services → Hotspot clustering: clusters reports
- Municipal staff → Spatial map: inspects geography (evidence: `README.md`)
- Upload signing API → Server session checks: checks session (evidence: `src/app/api/upload/signature/route.ts`)
- Upload signing API → Cloudinary: signs uploads