# dineshrajdhanapathydd/civicflow-ai architecture

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

## Overview

CivicFlow AI turns citizen text and photos into analyzed reports, groups duplicates into prioritized community issues, and exposes progress through staff controls and a dashboard. Citizens and staff use a React app backed by an API Lambda and DynamoDB; analysis also uses Rekognition and Bedrock. Ask CivicFlow is documented as a separate Strands-based Python agent. The excerpts show much of the Node analysis flow; some frontend routes, agent wiring, and AWS deployment links are supported only by the README, so those relationships are cited there.

Main entry points: [`backend/src/handler.ts`](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/handler.ts) (API router), [`backend/src/data/repo.ts`](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/data/repo.ts) (DynamoDB access), [`backend/src/services/analyze.ts`](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/analyze.ts) (Analysis pipeline), [`backend/src/services/clustering.ts`](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/clustering.ts) (Issue clustering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Community app"]
  node_report_form["Report form<br/>[ReportForm.tsx]"]
  node_issue_views["Issue views<br/>[IssueDetails.tsx]"]
  node_dashboard_view["Dashboard view<br/>[Dashboard.tsx]"]
  node_ask_view["Ask view<br/>[Ask.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and records"]
  node_api_router["API router<br/>[handler.ts]"]
  node_reports["Report management<br/>[reports.ts]"]
  node_uploads["Image uploads<br/>[uploads.ts]"]
  node_records["DynamoDB access<br/>[repo.ts]"]
  node_dashboard["Dashboard stats<br/>[dashboard.ts]"]
end

subgraph group_analysis["Issue analysis"]
  node_analysis_orchestrator["Analysis pipeline<br/>[analyze.ts]"]
  node_text_evidence["Text evidence<br/>[textEvidence.ts]"]
  node_vision["Image analysis<br/>[vision.ts]"]
  node_bedrock_reasoning["AI reasoning<br/>[bedrock.ts]"]
  node_clustering["Issue clustering<br/>[clustering.ts]"]
  node_similarity["Duplicate matching<br/>[similarity.ts]"]
  node_priority["Priority model<br/>[priority.ts]"]
end

subgraph group_ask["Ask CivicFlow"]
  node_ask_service["Ask service<br/>[ask.ts]"]
  node_agent_tools["Data tools<br/>[agentTools.ts]"]
  node_python_handler["Agent Lambda<br/>[handler.py]"]
  node_strands_agent["Strands agent<br/>[agent.py]"]
  node_agent_data["Agent data access<br/>[civicflow_data.py]"]
end

subgraph group_aws["AWS services"]
  node_dynamodb[("DynamoDB")]
  node_rekognition["Amazon Rekognition"]
  node_bedrock["Amazon Bedrock"]
  node_s3[("Amazon S3")]
  node_cloud_stack["AWS deployment<br/>[civicflow-stack.ts]"]
end

node_citizen(("Citizen"))
node_staff(("Staff"))

node_citizen -->|"submits evidence"| node_report_form
node_staff -->|"updates status"| node_issue_views
node_report_form -->|"sends requests"| node_api_client
node_issue_views -->|"loads and updates"| node_api_client
node_dashboard_view -->|"loads statistics"| node_api_client
node_ask_view -->|"asks question"| node_api_client
node_api_client -->|"calls API"| node_api_router
node_api_router -->|"creates and reads"| node_reports
node_api_router -->|"requests upload URL"| node_uploads
node_api_router -->|"starts analysis"| node_analysis_orchestrator
node_api_router -->|"loads issue details"| node_clustering
node_api_router -->|"updates status"| node_records
node_api_router -->|"gets statistics"| node_dashboard
node_api_router -->|"handles questions"| node_ask_service
node_reports -->|"persists reports"| node_records
node_records -->|"reads and writes"| node_dynamodb
node_uploads -->|"presigns image upload"| node_s3
node_analysis_orchestrator -->|"loads and saves reports"| node_records
node_analysis_orchestrator -->|"extracts evidence"| node_text_evidence
node_analysis_orchestrator -->|"analyzes image"| node_vision
node_vision -->|"detects image labels"| node_rekognition
node_analysis_orchestrator -->|"fuses evidence"| node_bedrock_reasoning
node_bedrock_reasoning -->|"reasons over evidence"| node_bedrock
node_bedrock_reasoning -->|"uses heuristic fallback"| node_text_evidence
node_analysis_orchestrator -->|"clusters analyzed report"| node_clustering
node_clustering -->|"matches reports"| node_similarity
node_clustering -->|"computes priority"| node_priority
node_clustering -->|"stores issues and links"| node_records
node_dashboard -->|"aggregates records"| node_records
node_ask_service -->|"retrieves live data"| node_agent_tools
node_agent_tools -->|"queries records"| node_records
node_python_handler -->|"invokes agent"| node_strands_agent
node_strands_agent -->|"uses data tools"| node_agent_data
node_cloud_stack -->|"deploys Lambda"| node_api_router
node_cloud_stack -->|"deploys agent Lambda"| node_python_handler
node_cloud_stack -->|"provisions store"| node_dynamodb
node_cloud_stack -->|"provisions buckets"| node_s3

click node_report_form "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/ReportForm.tsx"
click node_issue_views "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/IssueDetails.tsx"
click node_dashboard_view "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/Dashboard.tsx"
click node_ask_view "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/Ask.tsx"
click node_api_client "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/lib/api.ts"
click node_api_router "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/handler.ts"
click node_reports "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/reports.ts"
click node_uploads "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/uploads.ts"
click node_records "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/data/repo.ts"
click node_analysis_orchestrator "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/analyze.ts"
click node_text_evidence "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/textEvidence.ts"
click node_vision "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/vision.ts"
click node_bedrock_reasoning "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/bedrock.ts"
click node_clustering "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/clustering.ts"
click node_similarity "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/similarity.ts"
click node_priority "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/priority.ts"
click node_dashboard "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/dashboard.ts"
click node_ask_service "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/ask.ts"
click node_agent_tools "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/agentTools.ts"
click node_python_handler "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/handler.py"
click node_strands_agent "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/agent.py"
click node_agent_data "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/civicflow_data.py"
click node_cloud_stack "https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/infra/lib/civicflow-stack.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_report_form,node_issue_views,node_dashboard_view,node_ask_view,node_api_client toneBlue
class node_api_router,node_reports,node_uploads,node_records,node_dashboard toneAmber
class node_analysis_orchestrator,node_text_evidence,node_vision,node_bedrock_reasoning,node_clustering,node_similarity,node_priority toneMint
class node_ask_service,node_agent_tools,node_python_handler,node_strands_agent,node_agent_data toneRose
class node_dynamodb,node_rekognition,node_bedrock,node_s3,node_cloud_stack,node_citizen,node_staff toneIndigo
```

## Components

### Community app

- [Report form](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/ReportForm.tsx): `frontend/src/pages/ReportForm.tsx`
- [Issue views](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/IssueDetails.tsx): `frontend/src/pages/IssueDetails.tsx`
- [Dashboard view](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Ask view](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/pages/Ask.tsx): `frontend/src/pages/Ask.tsx`
- [API client](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and records

- [API router](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/handler.ts): `backend/src/handler.ts`
- [Report management](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/reports.ts): `backend/src/services/reports.ts`
- [Image uploads](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/uploads.ts): `backend/src/services/uploads.ts`
- [DynamoDB access](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/data/repo.ts): `backend/src/data/repo.ts`
- [Dashboard stats](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/dashboard.ts): `backend/src/services/dashboard.ts`

### Issue analysis

- [Analysis pipeline](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/analyze.ts): `backend/src/services/analyze.ts`
- [Text evidence](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/textEvidence.ts): `backend/src/services/textEvidence.ts`
- [Image analysis](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/vision.ts): `backend/src/services/vision.ts`
- [AI reasoning](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/bedrock.ts): `backend/src/services/bedrock.ts`
- [Issue clustering](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/clustering.ts): `backend/src/services/clustering.ts`
- [Duplicate matching](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/similarity.ts): `backend/src/services/similarity.ts`
- [Priority model](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/priority.ts): `backend/src/services/priority.ts`

### Ask CivicFlow

- [Ask service](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/ask.ts): `backend/src/services/ask.ts`
- [Data tools](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend/src/services/agentTools.ts): `backend/src/services/agentTools.ts`
- [Agent Lambda](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/handler.py): `backend-agent/handler.py`
- [Strands agent](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/agent.py): `backend-agent/agent.py`
- [Agent data access](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/backend-agent/civicflow_data.py): `backend-agent/civicflow_data.py`

### AWS services

- **DynamoDB**
- **Amazon Rekognition**
- **Amazon Bedrock**
- **Amazon S3**
- [AWS deployment](https://github.com/dineshrajdhanapathydd/civicflow-ai/blob/main/infra/lib/civicflow-stack.ts): `infra/lib/civicflow-stack.ts`

### Other components

- **Citizen**
- **Staff**

## Connections

- Citizen → Report form: submits evidence (evidence: `README.md`)
- Staff → Issue views: updates status (evidence: `README.md`)
- Report form → API client: sends requests (evidence: `frontend/src/pages/ReportForm.tsx`)
- Issue views → API client: loads and updates (evidence: `frontend/src/pages/IssueDetails.tsx`)
- Dashboard view → API client: loads statistics (evidence: `frontend/src/pages/Dashboard.tsx`)
- Ask view → API client: asks question (evidence: `frontend/src/pages/Ask.tsx`)
- API client → API router: calls API (evidence: `README.md`)
- API router → Report management: creates and reads (evidence: `backend/src/handler.ts`)
- API router → Image uploads: requests upload URL (evidence: `backend/src/handler.ts`)
- API router → Analysis pipeline: starts analysis (evidence: `backend/src/handler.ts`)
- API router → Issue clustering: loads issue details (evidence: `backend/src/handler.ts`)
- API router → DynamoDB access: updates status (evidence: `backend/src/handler.ts`)
- API router → Dashboard stats: gets statistics (evidence: `backend/src/handler.ts`)
- API router → Ask service: handles questions (evidence: `backend/src/handler.ts`)
- Report management → DynamoDB access: persists reports (evidence: `backend/src/services/reports.ts`)
- DynamoDB access → DynamoDB: reads and writes (evidence: `backend/src/data/repo.ts`)
- Image uploads → Amazon S3: presigns image upload (evidence: `README.md`)
- Analysis pipeline → DynamoDB access: loads and saves reports (evidence: `backend/src/services/analyze.ts`)
- Analysis pipeline → Text evidence: extracts evidence (evidence: `backend/src/services/analyze.ts`)
- Analysis pipeline → Image analysis: analyzes image (evidence: `backend/src/services/analyze.ts`)
- Image analysis → Amazon Rekognition: detects image labels (evidence: `README.md`)
- Analysis pipeline → AI reasoning: fuses evidence (evidence: `backend/src/services/analyze.ts`)
- AI reasoning → Amazon Bedrock: reasons over evidence (evidence: `README.md`)
- AI reasoning → Text evidence: uses heuristic fallback (evidence: `backend/src/services/bedrock.ts`)
- Analysis pipeline → Issue clustering: clusters analyzed report (evidence: `backend/src/services/analyze.ts`)
- Issue clustering → Duplicate matching: matches reports (evidence: `backend/src/services/clustering.ts`)
- Issue clustering → Priority model: computes priority (evidence: `backend/src/services/clustering.ts`)
- Issue clustering → DynamoDB access: stores issues and links (evidence: `backend/src/services/clustering.ts`)
- Dashboard stats → DynamoDB access: aggregates records (evidence: `backend/src/services/dashboard.ts`)
- Ask service → Data tools: retrieves live data (evidence: `backend/src/services/ask.ts`)
- Data tools → DynamoDB access: queries records (evidence: `backend/src/services/agentTools.ts`)
- Agent Lambda → Strands agent: invokes agent (evidence: `backend-agent/handler.py`)
- Strands agent → Agent data access: uses data tools (evidence: `backend-agent/agent.py`)
- AWS deployment → API router: deploys Lambda (evidence: `README.md`)
- AWS deployment → Agent Lambda: deploys agent Lambda (evidence: `README.md`)
- AWS deployment → DynamoDB: provisions store (evidence: `README.md`)
- AWS deployment → Amazon S3: provisions buckets (evidence: `README.md`)
