# satishmeher26/civiclens-ai architecture

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

- Interactive diagram: https://gitdiagram.com/satishmeher26/civiclens-ai
- Repository: https://github.com/satishmeher26/civiclens-ai

## Overview

CivicLens AI is a civic-issue reporting and municipal operations platform. Citizens submit and track geolocated complaints; backend services classify, deduplicate, score, and route them; municipal staff dispatch work and reviewers verify resolution. The product also exposes GIS and analytics for recurrence and hotspot intelligence. The graph follows documented workflows and source-index references; unsampled frontend and backend details are represented at subsystem level where exact implementation links are not shown.

Main entry points: [`backend/app/api/v1/reports_routes.py`](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/reports_routes.py) (Report intake), [`frontend/src/services/api.ts`](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/services/api.ts) (REST client), [`backend/app/api/v1/issues_routes.py`](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/issues_routes.py) (Issue lifecycle API), [`frontend/src/App.tsx`](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen reporting"]
  node_app["Web application<br/>[App.tsx]"]
  node_report_ui["Report wizard<br/>[ReportModal.tsx]"]
  node_track_ui["Issue tracking<br/>[TrackModal.tsx]"]
  node_api_client["REST client<br/>[api.ts]"]
end

subgraph group_intelligence["Issue intelligence"]
  node_report_routes["Report intake<br/>[reports_routes.py]"]
  node_classifier["AI classification"]
  node_duplicate["Duplicate detection"]
  node_priority["Priority scoring"]
  node_routing["Department routing<br/>[routing_service.py]"]
  node_genai["Generative AI<br/>[genai_service.py]"]
  node_domain["Civic issue model<br/>[domain.py]"]
end

subgraph group_operations["Municipal operations"]
  node_database[("Issue and report store<br/>[database.py]")]
  node_authority_ui["Authority desk"]
  node_issue_routes["Issue lifecycle API<br/>[issues_routes.py]"]
  node_verification["Work verification"]
  node_auth_ui["Role and session<br/>[AuthContext.tsx]"]
  node_auth_api["Authentication API<br/>[auth_routes.py]"]
  node_auth_service["Access control<br/>[auth_service.py]"]
end

subgraph group_insight["GIS and analytics"]
  node_gis_ui["GIS explorer<br/>[CivicMap.tsx]"]
  node_gis_api["GIS API<br/>[gis_routes.py]"]
  node_spatial["Spatial analysis<br/>[spatial_service.py]"]
  node_analytics_ui["Analytics dashboard"]
  node_analytics_api["Analytics API"]
  node_recurrence["Recurrence analysis"]
end

node_citizen_actor(("Citizen"))

node_citizen_actor -->|"uses"| node_app
node_app -->|"opens"| node_report_ui
node_app -->|"opens"| node_track_ui
node_report_ui -->|"submits report"| node_api_client
node_track_ui -.->|"requests tracking"| node_api_client
node_api_client -->|"calls report endpoints"| node_report_routes
node_api_client -->|"calls issue endpoints"| node_issue_routes
node_report_routes -->|"classifies"| node_classifier
node_report_routes -->|"checks duplicates"| node_duplicate
node_report_routes -->|"scores urgency"| node_priority
node_report_routes -->|"recommends department"| node_routing
node_report_routes -->|"stores report"| node_database
node_duplicate -->|"uses distance analysis"| node_spatial
node_priority -->|"uses proximity factors"| node_spatial
node_report_routes -.->|"requests AI assistance"| node_genai
node_report_routes -->|"builds issue records"| node_domain
node_authority_ui -->|"requests operations"| node_api_client
node_authority_ui -->|"is presented by"| node_app
node_issue_routes -->|"reads and updates"| node_database
node_issue_routes -->|"looks up department"| node_routing
node_issue_routes -.->|"verifies evidence"| node_verification
node_auth_ui -->|"authenticates"| node_auth_api
node_auth_api -->|"delegates authentication"| node_auth_service
node_auth_service -->|"reads and writes accounts"| node_database
node_gis_ui -.->|"requests map data"| node_gis_api
node_gis_api -->|"reads issues"| node_database
node_gis_api -->|"uses spatial analysis"| node_spatial
node_analytics_ui -.->|"requests analytics"| node_api_client
node_api_client -->|"calls analytics endpoints"| node_analytics_api
node_analytics_api -.->|"analyzes recurrence"| node_recurrence
node_recurrence -->|"uses spatial analysis"| node_spatial

click node_app "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/App.tsx"
click node_report_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/citizen/ReportModal.tsx"
click node_track_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/citizen/TrackModal.tsx"
click node_api_client "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/services/api.ts"
click node_report_routes "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/reports_routes.py"
click node_classifier "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/classification_service.py"
click node_duplicate "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/duplicate_service.py"
click node_priority "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/priority_service.py"
click node_routing "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/routing_service.py"
click node_genai "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/genai_service.py"
click node_domain "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/models/domain.py"
click node_database "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/core/database.py"
click node_authority_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/pages/AuthorityPortal.tsx"
click node_issue_routes "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/issues_routes.py"
click node_verification "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/verification_service.py"
click node_auth_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/context/AuthContext.tsx"
click node_auth_api "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/auth_routes.py"
click node_auth_service "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/auth_service.py"
click node_gis_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/gis/CivicMap.tsx"
click node_gis_api "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/gis_routes.py"
click node_spatial "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/spatial_service.py"
click node_analytics_ui "https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/analytics/AnalyticsDashboard.tsx"
click node_analytics_api "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/analytics_routes.py"
click node_recurrence "https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/recurrence_service.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_app,node_report_ui,node_track_ui,node_api_client toneBlue
class node_report_routes,node_classifier,node_duplicate,node_priority,node_routing,node_genai,node_domain toneAmber
class node_database,node_authority_ui,node_issue_routes,node_verification,node_auth_ui,node_auth_api,node_auth_service toneMint
class node_gis_ui,node_gis_api,node_spatial,node_analytics_ui,node_analytics_api,node_recurrence toneRose
class node_citizen_actor toneIndigo
```

## Components

### Citizen reporting

- [Web application](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Report wizard](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/citizen/ReportModal.tsx): `frontend/src/components/citizen/ReportModal.tsx`
- [Issue tracking](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/citizen/TrackModal.tsx): `frontend/src/components/citizen/TrackModal.tsx`
- [REST client](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Issue intelligence

- [Report intake](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/reports_routes.py): `backend/app/api/v1/reports_routes.py`
- [AI classification](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/classification_service.py): `backend/app/services/classification_service.py`
- [Duplicate detection](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/duplicate_service.py): `backend/app/services/duplicate_service.py`
- [Priority scoring](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/priority_service.py): `backend/app/services/priority_service.py`
- [Department routing](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/routing_service.py): `backend/app/services/routing_service.py`
- [Generative AI](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/genai_service.py): `backend/app/services/genai_service.py`
- [Civic issue model](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/models/domain.py): `backend/app/models/domain.py`

### Municipal operations

- [Issue and report store](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Authority desk](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/pages/AuthorityPortal.tsx): `frontend/src/pages/AuthorityPortal.tsx`
- [Issue lifecycle API](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/issues_routes.py): `backend/app/api/v1/issues_routes.py`
- [Work verification](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/verification_service.py): `backend/app/services/verification_service.py`
- [Role and session](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Authentication API](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/auth_routes.py): `backend/app/api/v1/auth_routes.py`
- [Access control](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### GIS and analytics

- [GIS explorer](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/gis/CivicMap.tsx): `frontend/src/components/gis/CivicMap.tsx`
- [GIS API](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/gis_routes.py): `backend/app/api/v1/gis_routes.py`
- [Spatial analysis](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/spatial_service.py): `backend/app/services/spatial_service.py`
- [Analytics dashboard](https://github.com/satishmeher26/civiclens-ai/blob/main/frontend/src/components/analytics/AnalyticsDashboard.tsx): `frontend/src/components/analytics/AnalyticsDashboard.tsx`
- [Analytics API](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/api/v1/analytics_routes.py): `backend/app/api/v1/analytics_routes.py`
- [Recurrence analysis](https://github.com/satishmeher26/civiclens-ai/blob/main/backend/app/services/recurrence_service.py): `backend/app/services/recurrence_service.py`

### Other components

- **Citizen**

## Connections

- Citizen → Web application: uses (evidence: `README.md`)
- Web application → Report wizard: opens (evidence: `frontend/src/App.tsx`)
- Web application → Issue tracking: opens (evidence: `frontend/src/App.tsx`)
- Report wizard → REST client: submits report (evidence: `frontend/src/components/citizen/ReportModal.tsx`)
- Issue tracking → REST client: requests tracking
- REST client → Report intake: calls report endpoints (evidence: `frontend/src/services/api.ts`)
- REST client → Issue lifecycle API: calls issue endpoints (evidence: `frontend/src/services/api.ts`)
- Report intake → AI classification: classifies (evidence: `backend/app/api/v1/reports_routes.py`)
- Report intake → Duplicate detection: checks duplicates (evidence: `backend/app/api/v1/reports_routes.py`)
- Report intake → Priority scoring: scores urgency (evidence: `backend/app/api/v1/reports_routes.py`)
- Report intake → Department routing: recommends department (evidence: `backend/app/api/v1/reports_routes.py`)
- Report intake → Issue and report store: stores report (evidence: `backend/app/api/v1/reports_routes.py`)
- Duplicate detection → Spatial analysis: uses distance analysis (evidence: `backend/app/services/duplicate_service.py`)
- Priority scoring → Spatial analysis: uses proximity factors (evidence: `backend/app/services/priority_service.py`)
- Report intake → Generative AI: requests AI assistance
- Report intake → Civic issue model: builds issue records (evidence: `backend/app/api/v1/reports_routes.py`)
- Authority desk → REST client: requests operations (evidence: `frontend/src/pages/AuthorityPortal.tsx`)
- Authority desk → Web application: is presented by (evidence: `frontend/src/App.tsx`)
- Issue lifecycle API → Issue and report store: reads and updates (evidence: `backend/app/api/v1/issues_routes.py`)
- Issue lifecycle API → Department routing: looks up department (evidence: `backend/app/api/v1/issues_routes.py`)
- Issue lifecycle API → Work verification: verifies evidence (evidence: `backend/app/api/v1/issues_routes.py`)
- Role and session → Authentication API: authenticates (evidence: `frontend/src/context/AuthContext.tsx`)
- Authentication API → Access control: delegates authentication (evidence: `backend/app/api/v1/auth_routes.py`)
- Access control → Issue and report store: reads and writes accounts (evidence: `backend/app/services/auth_service.py`)
- GIS explorer → GIS API: requests map data
- GIS API → Issue and report store: reads issues (evidence: `backend/app/api/v1/gis_routes.py`)
- GIS API → Spatial analysis: uses spatial analysis (evidence: `backend/app/api/v1/gis_routes.py`)
- Analytics dashboard → REST client: requests analytics
- REST client → Analytics API: calls analytics endpoints (evidence: `frontend/src/services/api.ts`)
- Analytics API → Recurrence analysis: analyzes recurrence
- Recurrence analysis → Spatial analysis: uses spatial analysis (evidence: `backend/app/services/recurrence_service.py`)
