# ilmaan-ahamed/civicpulse-lk architecture

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

- Interactive diagram: https://gitdiagram.com/ilmaan-ahamed/civicpulse-lk
- Repository: https://github.com/ilmaan-ahamed/civicpulse-lk
- Video tour (about a minute): https://gitdiagram.com/ilmaan-ahamed/civicpulse-lk/video

## Overview

CivicPulse LK is a civic-issue reporting and resolution application. The main workflow is citizen report submission, verification, assignment to an agency, field inspection, and resolution; dashboards and public transparency expose progress. Role-based pages also support agency management, NGO pledges, notifications, and administration. The README is a generic Next.js starter and does not document product capabilities; this map relies on the supplied tree and sampled API source, so uncertain subsystem wiring is omitted.

Main entry points: [`src/lib/db.ts`](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/db.ts) (Application database), [`src/lib/auth-guard.ts`](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/auth-guard.ts) (Role authorization), [`src/app/api/reports/route.ts`](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/reports/route.ts) (Report API), [`src/app/api/verifications/route.ts`](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/verifications/route.ts) (Verifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Role-based pages<br/>[page.tsx]"]
  node_reportform["Report submission<br/>[page.tsx]"]
  node_agencyui["Agency console<br/>[page.tsx]"]
end

subgraph group_reporting["Reports and verification"]
  node_reportapi["Report API<br/>[route.ts]"]
  node_reportdetail["Report management<br/>[route.ts]"]
  node_issue["Issue creation<br/>[issue.ts]"]
  node_triage["AI triage<br/>[triage.ts]"]
  node_verifyqueue["Verification queue<br/>[route.ts]"]
  node_verification["Verifications<br/>[route.ts]"]
  node_trust["Trust scoring<br/>[trust-score.ts]"]
end

subgraph group_resolution["Resolution operations"]
  node_agencies["Agency management<br/>[route.ts]"]
  node_assignments["Assignments<br/>[route.ts]"]
  node_inspections["Field inspections<br/>[route.ts]"]
  node_pledges["NGO pledges<br/>[route.ts]"]
end

subgraph group_insight["Transparency and insights"]
  node_dashboardapi["Dashboard data<br/>[route.ts]"]
  node_dashboardui["Dashboard views"]
  node_publicview["Public transparency<br/>[page.tsx]"]
end

subgraph group_platform["Shared platform"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_auth["Role authorization<br/>[auth-guard.ts]"]
  node_database[("Application database<br/>[db.ts]")]
end

node_citizen(("Citizen"))
node_staff(("Civic staff"))

node_citizen -->|"uses"| node_web
node_staff -->|"uses"| node_web
node_web -->|"opens"| node_reportform
node_reportform -->|"submits"| node_reportapi
node_reportapi -->|"creates via"| node_issue
node_reportapi -->|"queries"| node_database
node_reportdetail -->|"reads and updates"| node_database
node_verifyqueue -->|"queries"| node_database
node_verification -->|"reads and writes"| node_database
node_verification -->|"updates score"| node_trust
node_agencies -->|"reads and writes"| node_database
node_agencyui -->|"manages"| node_agencies
node_assignments -->|"reads and writes"| node_database
node_assignments -->|"notifies"| node_notifications
node_inspections -->|"reads and writes"| node_database
node_pledges -->|"reads and writes"| node_database
node_dashboardapi -->|"queries"| node_database
node_dashboardui -->|"fetches"| node_dashboardapi
node_publicview -->|"fetches"| node_dashboardapi
node_reportapi -.->|"authorizes"| node_auth
node_reportdetail -->|"authorizes"| node_auth
node_verification -->|"authorizes"| node_auth
node_assignments -->|"authorizes"| node_auth
node_inspections -->|"authorizes"| node_auth
node_pledges -->|"authorizes"| node_auth

click node_web "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/dashboard/citizen/page.tsx"
click node_reportform "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/dashboard/citizen/report/page.tsx"
click node_agencyui "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/(protected)/ds-console/agencies/page.tsx"
click node_reportapi "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/reports/route.ts"
click node_reportdetail "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/reports/%5Bid%5D/route.ts"
click node_issue "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/db/issue.ts"
click node_triage "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/ai/triage.ts"
click node_verifyqueue "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/verification-queue/route.ts"
click node_verification "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/verifications/route.ts"
click node_trust "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/trust-score.ts"
click node_agencies "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/agencies/route.ts"
click node_assignments "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/assignments/route.ts"
click node_inspections "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/inspections/route.ts"
click node_pledges "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/pledges/route.ts"
click node_notifications "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/tracking/notifications.ts"
click node_dashboardapi "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/dashboard/route.ts"
click node_dashboardui "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/components/dashboard/dashboard-client.tsx"
click node_publicview "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/transparency/page.tsx"
click node_auth "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/auth-guard.ts"
click node_database "https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/db.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_web,node_reportform,node_agencyui toneBlue
class node_reportapi,node_reportdetail,node_issue,node_triage,node_verifyqueue,node_verification,node_trust toneAmber
class node_agencies,node_assignments,node_inspections,node_pledges toneMint
class node_dashboardapi,node_dashboardui,node_publicview toneRose
class node_notifications,node_auth,node_database,node_citizen,node_staff toneIndigo
```

## Components

### User experience

- [Role-based pages](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/dashboard/citizen/page.tsx): `src/app/dashboard/citizen/page.tsx`
- [Report submission](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/dashboard/citizen/report/page.tsx): `src/app/dashboard/citizen/report/page.tsx`
- [Agency console](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/(protected)/ds-console/agencies/page.tsx): `src/app/(protected)/ds-console/agencies/page.tsx`

### Reports and verification

- [Report API](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/reports/route.ts): `src/app/api/reports/route.ts`
- [Report management](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/reports/%5Bid%5D/route.ts): `src/app/api/reports/[id]/route.ts`
- [Issue creation](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/db/issue.ts): `src/lib/db/issue.ts`
- [AI triage](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/ai/triage.ts): `src/lib/ai/triage.ts`
- [Verification queue](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/verification-queue/route.ts): `src/app/api/verification-queue/route.ts`
- [Verifications](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/verifications/route.ts): `src/app/api/verifications/route.ts`
- [Trust scoring](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/trust-score.ts): `src/lib/trust-score.ts`

### Resolution operations

- [Agency management](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/agencies/route.ts): `src/app/api/agencies/route.ts`
- [Assignments](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/assignments/route.ts): `src/app/api/assignments/route.ts`
- [Field inspections](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/inspections/route.ts): `src/app/api/inspections/route.ts`
- [NGO pledges](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/pledges/route.ts): `src/app/api/pledges/route.ts`

### Transparency and insights

- [Dashboard data](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/api/dashboard/route.ts): `src/app/api/dashboard/route.ts`
- [Dashboard views](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/components/dashboard/dashboard-client.tsx): `src/components/dashboard/dashboard-client.tsx`
- [Public transparency](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/app/transparency/page.tsx): `src/app/transparency/page.tsx`

### Shared platform

- [Notifications](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/tracking/notifications.ts): `src/lib/tracking/notifications.ts`
- [Role authorization](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/auth-guard.ts): `src/lib/auth-guard.ts`
- [Application database](https://github.com/ilmaan-ahamed/civicpulse-lk/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Other components

- **Citizen**
- **Civic staff**

## Connections

- Citizen → Role-based pages: uses
- Civic staff → Role-based pages: uses
- Role-based pages → Report submission: opens
- Report submission → Report API: submits
- Report API → Issue creation: creates via
- Report API → Application database: queries
- Report management → Application database: reads and updates
- Verification queue → Application database: queries
- Verifications → Application database: reads and writes
- Verifications → Trust scoring: updates score
- Agency management → Application database: reads and writes
- Agency console → Agency management: manages
- Assignments → Application database: reads and writes
- Assignments → Notifications: notifies
- Field inspections → Application database: reads and writes
- NGO pledges → Application database: reads and writes
- Dashboard data → Application database: queries
- Dashboard views → Dashboard data: fetches
- Public transparency → Dashboard data: fetches
- Report API → Role authorization: authorizes
- Report management → Role authorization: authorizes
- Verifications → Role authorization: authorizes
- Assignments → Role authorization: authorizes
- Field inspections → Role authorization: authorizes
- NGO pledges → Role authorization: authorizes