# debadritapaul26/civic-lense architecture

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

- Interactive diagram: https://gitdiagram.com/debadritapaul26/civic-lense
- Repository: https://github.com/debadritapaul26/civic-lense

## Overview

Civic-Lense is a civic-complaint analysis and decision-support platform. Citizens submit geolocated complaints, optionally with evidence; the backend classifies and stores them, then exposes location clusters, urgency rankings, and district aggregates for dashboards. A separate policy-simulation workflow evaluates selected clusters and a budget with specialist agents before an arbiter returns recommendations. The graph reflects the documented routes and sampled calls; several route, agent, and orchestration implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`civic-ai-platform/backend/main.py`](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/main.py) (FastAPI application), [`civic-ai-platform/frontend/app`](https://github.com/debadritapaul26/civic-lense/tree/main/civic-ai-platform/frontend/app) (Web application), [`civic-ai-platform/frontend/lib/api.ts`](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/lib/api.ts) (Frontend API client), [`civic-ai-platform/backend/database.py`](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/database.py) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web application"]
  node_api_client["Frontend API client<br/>[api.ts]"]
  node_complaint_ui["Complaint form<br/>[ComplaintForm.tsx]"]
  node_dashboard["Civic dashboards<br/>[page.tsx]"]
  node_priority_ui["Urgency panel"]
  node_simulation_ui["Simulation views<br/>[page.tsx]"]
end

subgraph group_intake["Complaint intake"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_complaints["Complaint endpoints<br/>[complaints.py]"]
  node_nlu["Complaint NLU<br/>[nlu_agent.py]"]
  node_evidence["Evidence uploads<br/>[complaints.py]"]
end

subgraph group_analysis["Civic analysis"]
  node_clusters["Cluster endpoints<br/>[clusters.py]"]
  node_cluster_service["Location clustering"]
  node_insights["Urgency insights<br/>[insights.py]"]
  node_urgency["Urgency ranking"]
  node_aggregation_router["Aggregation endpoints<br/>[aggregation.py]"]
  node_aggregation["District aggregation"]
end

subgraph group_simulation["Policy simulation"]
  node_simulation_router["Simulation endpoints<br/>[simulation.py]"]
  node_orchestrator["Simulation coordinator<br/>[orchestrator.py]"]
  node_agent_runner["Agent runner<br/>[agent_runner.py]"]
  node_specialists{{"Specialist agents"}}
  node_arbiter{{"Arbiter agent<br/>[arbiter_agent.py]"}}
end

subgraph group_state["Persistence"]
  node_database[("Application database<br/>[database.py]")]
end

node_citizen(("Citizen or analyst"))
node_claude(("Claude API"))

node_citizen -->|"uses"| node_frontend
node_frontend -->|"presents"| node_complaint_ui
node_frontend -->|"presents"| node_dashboard
node_frontend -->|"presents"| node_priority_ui
node_frontend -->|"presents"| node_simulation_ui
node_complaint_ui -->|"submits"| node_api_client
node_dashboard -->|"requests data"| node_api_client
node_priority_ui -->|"requests rankings"| node_api_client
node_simulation_ui -->|"runs and retrieves"| node_api_client
node_api_client -->|"HTTP requests"| node_backend
node_backend -->|"dispatches"| node_complaints
node_backend -->|"dispatches"| node_clusters
node_backend -->|"dispatches"| node_insights
node_backend -->|"dispatches"| node_aggregation_router
node_backend -->|"dispatches"| node_simulation_router
node_complaints -->|"classifies text"| node_nlu
node_complaints -->|"saves uploads"| node_evidence
node_complaints -->|"reads and writes"| node_database
node_evidence -->|"stores metadata"| node_database
node_clusters -->|"builds clusters"| node_cluster_service
node_cluster_service -->|"reads complaints"| node_database
node_insights -->|"ranks locations"| node_urgency
node_urgency -->|"uses clusters"| node_cluster_service
node_aggregation_router -->|"computes statistics"| node_aggregation
node_aggregation -->|"reads and writes"| node_database
node_simulation_router -->|"runs simulations"| node_orchestrator
node_orchestrator -->|"loads inputs and saves results"| node_database
node_orchestrator -->|"loads urgency context"| node_urgency
node_orchestrator -->|"invokes agents"| node_agent_runner
node_agent_runner -->|"runs specialists"| node_specialists
node_agent_runner -->|"runs arbiter"| node_arbiter
node_specialists -.->|"requests analysis"| node_claude
node_arbiter -.->|"requests decision"| node_claude

click node_frontend "https://github.com/debadritapaul26/civic-lense/tree/main/civic-ai-platform/frontend/app"
click node_api_client "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/lib/api.ts"
click node_complaint_ui "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/components/ComplaintForm.tsx"
click node_dashboard "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/app/dashboard/page.tsx"
click node_priority_ui "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/components/UrgencyPriorityPanel.tsx"
click node_simulation_ui "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/app/simulations/page.tsx"
click node_backend "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/main.py"
click node_complaints "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/complaints.py"
click node_nlu "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/agents/nlu_agent.py"
click node_evidence "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/complaints.py"
click node_clusters "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/clusters.py"
click node_cluster_service "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/location_cluster_service.py"
click node_insights "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/insights.py"
click node_urgency "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/urgency_ranking_service.py"
click node_aggregation_router "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/aggregation.py"
click node_aggregation "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/aggregation_service.py"
click node_simulation_router "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/simulation.py"
click node_orchestrator "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/orchestrator.py"
click node_agent_runner "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/agent_runner.py"
click node_specialists "https://github.com/debadritapaul26/civic-lense/tree/main/civic-ai-platform/backend/agents"
click node_arbiter "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/agents/arbiter_agent.py"
click node_database "https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/database.py"

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_frontend,node_api_client,node_complaint_ui,node_dashboard,node_priority_ui,node_simulation_ui toneBlue
class node_backend,node_complaints,node_nlu,node_evidence toneAmber
class node_clusters,node_cluster_service,node_insights,node_urgency,node_aggregation_router,node_aggregation,node_claude toneMint
class node_simulation_router,node_orchestrator,node_agent_runner,node_specialists,node_arbiter toneRose
class node_database,node_citizen toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/debadritapaul26/civic-lense/tree/main/civic-ai-platform/frontend/app): `civic-ai-platform/frontend/app`
- [Frontend API client](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/lib/api.ts): `civic-ai-platform/frontend/lib/api.ts`
- [Complaint form](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/components/ComplaintForm.tsx): `civic-ai-platform/frontend/components/ComplaintForm.tsx`
- [Civic dashboards](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/app/dashboard/page.tsx): `civic-ai-platform/frontend/app/dashboard/page.tsx`
- [Urgency panel](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/components/UrgencyPriorityPanel.tsx): `civic-ai-platform/frontend/components/UrgencyPriorityPanel.tsx`
- [Simulation views](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/frontend/app/simulations/page.tsx): `civic-ai-platform/frontend/app/simulations/page.tsx`

### Complaint intake

- [FastAPI application](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/main.py): `civic-ai-platform/backend/main.py`
- [Complaint endpoints](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/complaints.py): `civic-ai-platform/backend/routers/complaints.py`
- [Complaint NLU](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/agents/nlu_agent.py): `civic-ai-platform/backend/agents/nlu_agent.py`
- [Evidence uploads](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/complaints.py): `civic-ai-platform/backend/routers/complaints.py`

### Civic analysis

- [Cluster endpoints](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/clusters.py): `civic-ai-platform/backend/routers/clusters.py`
- [Location clustering](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/location_cluster_service.py): `civic-ai-platform/backend/services/location_cluster_service.py`
- [Urgency insights](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/insights.py): `civic-ai-platform/backend/routers/insights.py`
- [Urgency ranking](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/urgency_ranking_service.py): `civic-ai-platform/backend/services/urgency_ranking_service.py`
- [Aggregation endpoints](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/aggregation.py): `civic-ai-platform/backend/routers/aggregation.py`
- [District aggregation](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/aggregation_service.py): `civic-ai-platform/backend/services/aggregation_service.py`

### Policy simulation

- [Simulation endpoints](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/routers/simulation.py): `civic-ai-platform/backend/routers/simulation.py`
- [Simulation coordinator](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/orchestrator.py): `civic-ai-platform/backend/services/orchestrator.py`
- [Agent runner](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/services/agent_runner.py): `civic-ai-platform/backend/services/agent_runner.py`
- [Specialist agents](https://github.com/debadritapaul26/civic-lense/tree/main/civic-ai-platform/backend/agents): `civic-ai-platform/backend/agents`
- [Arbiter agent](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/agents/arbiter_agent.py): `civic-ai-platform/backend/agents/arbiter_agent.py`

### Persistence

- [Application database](https://github.com/debadritapaul26/civic-lense/blob/main/civic-ai-platform/backend/database.py): `civic-ai-platform/backend/database.py`

### Other components

- **Citizen or analyst**
- **Claude API**

## Connections

- Citizen or analyst → Web application: uses
- Web application → Complaint form: presents
- Web application → Civic dashboards: presents
- Web application → Urgency panel: presents
- Web application → Simulation views: presents
- Complaint form → Frontend API client: submits
- Civic dashboards → Frontend API client: requests data
- Urgency panel → Frontend API client: requests rankings
- Simulation views → Frontend API client: runs and retrieves
- Frontend API client → FastAPI application: HTTP requests
- FastAPI application → Complaint endpoints: dispatches
- FastAPI application → Cluster endpoints: dispatches
- FastAPI application → Urgency insights: dispatches
- FastAPI application → Aggregation endpoints: dispatches
- FastAPI application → Simulation endpoints: dispatches
- Complaint endpoints → Complaint NLU: classifies text
- Complaint endpoints → Evidence uploads: saves uploads
- Complaint endpoints → Application database: reads and writes
- Evidence uploads → Application database: stores metadata
- Cluster endpoints → Location clustering: builds clusters
- Location clustering → Application database: reads complaints
- Urgency insights → Urgency ranking: ranks locations
- Urgency ranking → Location clustering: uses clusters
- Aggregation endpoints → District aggregation: computes statistics
- District aggregation → Application database: reads and writes
- Simulation endpoints → Simulation coordinator: runs simulations
- Simulation coordinator → Application database: loads inputs and saves results
- Simulation coordinator → Urgency ranking: loads urgency context
- Simulation coordinator → Agent runner: invokes agents
- Agent runner → Specialist agents: runs specialists
- Agent runner → Arbiter agent: runs arbiter
- Specialist agents → Claude API: requests analysis
- Arbiter agent → Claude API: requests decision