# nithinkumar2704/civic_bridge architecture

> Architecture diagram of the GitHub repository nithinkumar2704/civic_bridge, 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/nithinkumar2704/civic_bridge
- Repository: https://github.com/nithinkumar2704/civic_bridge

## Overview

CivicBridge AI turns citizen reports into persistent, clustered civic issues, then supports municipal triage, response, resolution verification, and recurrence detection. Citizens and authorities use separate portal views backed by a FastAPI API. Complaint understanding and evidence/priority assessment feed issue clustering; Hindsight memory supplies recurrence context while the application database remains the system of record. The README documents analytics, assistant memory, and an eight-step demo; their wiring is only partly shown in sampled source, so uncertain internal links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/complaints.py`](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/complaints.py) (Complaints API), [`backend/app/database/session.py`](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/database/session.py) (Database session), [`backend/app/models/complaint.py`](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/complaint.py) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Civic portals"]
  node_citizen_view["Citizen portal<br/>[CitizenView.tsx]"]
  node_government_view["Government portal<br/>[GovernmentView.tsx]"]
  node_analytics_view["Analytics view<br/>[AnalyticsView.tsx]"]
  node_demo_view["Demo scenario"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_intake["Complaint intelligence"]
  node_complaints_api["Complaints API<br/>[complaints.py]"]
  node_ai_service["Complaint understanding<br/>[ai_service.py]"]
  node_routing_agent["Classification and routing"]
end

subgraph group_operations["Issue operations"]
  node_issues_api["Issues API<br/>[issues.py]"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
  node_demo_api["Demo API<br/>[demo.py]"]
  node_clustering["Issue clustering and scoring"]
end

subgraph group_memory["Memory and insight"]
  node_assistant_api["Assistant API<br/>[assistant.py]"]
  node_memory_agent["Memory context agent"]
  node_hindsight["Hindsight memory service"]
end

subgraph group_foundation["Application foundation"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_db_session["Database session<br/>[session.py]"]
  node_app_db[("Application database<br/>[complaint.py]")]
  node_identity_model["User records<br/>[user.py]"]
  node_cluster_model["Issue cluster records<br/>[issue_cluster.py]"]
  node_authority_response["Department actions"]
  node_resolution_model["Resolution confirmations"]
end

node_citizen(("Citizen"))
node_authority(("Municipal authority"))
node_hindsight_cluster{{"Hindsight service"}}

node_citizen -->|"reports and verifies"| node_citizen_view
node_authority -->|"triages and responds"| node_government_view
node_citizen_view -->|"requests services"| node_api_client
node_government_view -->|"requests services"| node_api_client
node_analytics_view -->|"requests analytics"| node_api_client
node_demo_view -->|"runs scenario"| node_api_client
node_api_client -->|"REST requests"| node_api_app
node_api_app -->|"dispatches routes"| node_auth_api
node_api_app -->|"dispatches routes"| node_complaints_api
node_api_app -->|"dispatches routes"| node_issues_api
node_api_app -->|"dispatches routes"| node_analytics_api
node_api_app -->|"dispatches routes"| node_assistant_api
node_api_app -->|"dispatches routes"| node_demo_api
node_complaints_api -->|"understands reports"| node_ai_service
node_complaints_api -->|"routes category"| node_routing_agent
node_complaints_api -->|"clusters complaints"| node_clustering
node_issues_api -->|"manages clusters"| node_clustering
node_complaints_api -->|"retains context"| node_memory_agent
node_memory_agent -->|"recalls and retains"| node_hindsight
node_clustering -->|"recalls and records"| node_hindsight
node_hindsight -.->|"memory operations"| node_hindsight_cluster
node_auth_api -->|"queries users"| node_db_session
node_complaints_api -->|"persists complaints"| node_db_session
node_issues_api -->|"persists issue actions"| node_db_session
node_analytics_api -->|"reads metrics"| node_db_session
node_demo_api -->|"resets demo data"| node_db_session
node_db_session -->|"reads and writes"| node_app_db
node_app_db -->|"stores identities"| node_identity_model
node_app_db -->|"stores clusters"| node_cluster_model
node_app_db -->|"stores actions"| node_authority_response
node_app_db -->|"stores confirmations"| node_resolution_model

click node_citizen_view "https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/CitizenView.tsx"
click node_government_view "https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/GovernmentView.tsx"
click node_analytics_view "https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/AnalyticsView.tsx"
click node_demo_view "https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/DemoScenarioStepper.tsx"
click node_api_client "https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/services/api.ts"
click node_api_app "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/auth.py"
click node_complaints_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/complaints.py"
click node_issues_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/issues.py"
click node_analytics_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/analytics.py"
click node_assistant_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/assistant.py"
click node_demo_api "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/demo.py"
click node_ai_service "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/ai_service.py"
click node_routing_agent "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/agents/classification_routing_agent.py"
click node_clustering "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/clustering_service.py"
click node_memory_agent "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/agents/memory_context_agent.py"
click node_hindsight "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/hindsight_service.py"
click node_db_session "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/database/session.py"
click node_app_db "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/complaint.py"
click node_identity_model "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/user.py"
click node_cluster_model "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/issue_cluster.py"
click node_authority_response "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/department_action.py"
click node_resolution_model "https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/resolution_confirmation.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_citizen_view,node_government_view,node_analytics_view,node_demo_view,node_api_client toneBlue
class node_complaints_api,node_ai_service,node_routing_agent toneAmber
class node_issues_api,node_analytics_api,node_demo_api,node_clustering toneMint
class node_assistant_api,node_memory_agent,node_hindsight toneRose
class node_api_app,node_auth_api,node_db_session,node_app_db,node_identity_model,node_cluster_model,node_authority_response,node_resolution_model,node_citizen,node_authority,node_hindsight_cluster toneIndigo
```

## Components

### Civic portals

- [Citizen portal](https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/CitizenView.tsx): `frontend/components/CitizenView.tsx`
- [Government portal](https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/GovernmentView.tsx): `frontend/components/GovernmentView.tsx`
- [Analytics view](https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/AnalyticsView.tsx): `frontend/components/AnalyticsView.tsx`
- [Demo scenario](https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/components/DemoScenarioStepper.tsx): `frontend/components/DemoScenarioStepper.tsx`
- [Frontend API client](https://github.com/nithinkumar2704/civic_bridge/blob/main/frontend/services/api.ts): `frontend/services/api.ts`

### Complaint intelligence

- [Complaints API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/complaints.py): `backend/app/api/complaints.py`
- [Complaint understanding](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Classification and routing](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/agents/classification_routing_agent.py): `backend/app/agents/classification_routing_agent.py`

### Issue operations

- [Issues API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/issues.py): `backend/app/api/issues.py`
- [Analytics API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [Demo API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/demo.py): `backend/app/api/demo.py`
- [Issue clustering and scoring](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/clustering_service.py): `backend/app/services/clustering_service.py`

### Memory and insight

- [Assistant API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/assistant.py): `backend/app/api/assistant.py`
- [Memory context agent](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/agents/memory_context_agent.py): `backend/app/agents/memory_context_agent.py`
- [Hindsight memory service](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/services/hindsight_service.py): `backend/app/services/hindsight_service.py`

### Application foundation

- [FastAPI application](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Database session](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Application database](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/complaint.py): `backend/app/models/complaint.py`
- [User records](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Issue cluster records](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/issue_cluster.py): `backend/app/models/issue_cluster.py`
- [Department actions](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/department_action.py): `backend/app/models/department_action.py`
- [Resolution confirmations](https://github.com/nithinkumar2704/civic_bridge/blob/main/backend/app/models/resolution_confirmation.py): `backend/app/models/resolution_confirmation.py`

### Other components

- **Citizen**
- **Municipal authority**
- **Hindsight service**

## Connections

- Citizen → Citizen portal: reports and verifies
- Municipal authority → Government portal: triages and responds
- Citizen portal → Frontend API client: requests services
- Government portal → Frontend API client: requests services
- Analytics view → Frontend API client: requests analytics
- Demo scenario → Frontend API client: runs scenario
- Frontend API client → FastAPI application: REST requests
- FastAPI application → Authentication API: dispatches routes
- FastAPI application → Complaints API: dispatches routes
- FastAPI application → Issues API: dispatches routes
- FastAPI application → Analytics API: dispatches routes
- FastAPI application → Assistant API: dispatches routes
- FastAPI application → Demo API: dispatches routes
- Complaints API → Complaint understanding: understands reports
- Complaints API → Classification and routing: routes category
- Complaints API → Issue clustering and scoring: clusters complaints
- Issues API → Issue clustering and scoring: manages clusters
- Complaints API → Memory context agent: retains context
- Memory context agent → Hindsight memory service: recalls and retains
- Issue clustering and scoring → Hindsight memory service: recalls and records
- Hindsight memory service → Hindsight service: memory operations
- Authentication API → Database session: queries users
- Complaints API → Database session: persists complaints
- Issues API → Database session: persists issue actions
- Analytics API → Database session: reads metrics
- Demo API → Database session: resets demo data
- Database session → Application database: reads and writes
- Application database → User records: stores identities
- Application database → Issue cluster records: stores clusters
- Application database → Department actions: stores actions
- Application database → Resolution confirmations: stores confirmations