# monolithic-dev/pramaan architecture

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

## Overview

Pramaan turns citizen reports into prioritized public works and closes the loop with funding, project tracking, and citizen confirmation. The documented workflow spans web and messaging intake, asynchronous AI processing and deduplication, scoring, scheme and budget decisions, and follow-up. The graph also shows the officer insights and public transparency branches. Sampled source confirms gateway registration, ingestion publishing and persistence, and worker dispatch; some feature internals are represented by their listed source paths, with uncertain call wiring omitted.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/monolithic-dev/pramaan/blob/main/apps/web/src/App.tsx) (Citizen and officer app), [`apps/api-gateway/src/store/firestoreStore.ts`](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/store/firestoreStore.ts) (Operational records), [`apps/api-gateway/src/services/ingestSubmission.ts`](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/services/ingestSubmission.ts) (Submission ingestion), [`apps/api-gateway/src/app.ts`](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/app.ts) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Citizen channels"]
  node_web["Citizen and officer app<br/>[App.tsx]"]
  node_offline["Offline report queue<br/>[useOfflineQueue.ts]"]
end

subgraph group_gateway["API gateway"]
  node_gateway_app["HTTP API<br/>[app.ts]"]
  node_submission_routes["Submission routes<br/>[submissions.ts]"]
  node_webhook_routes["Channel webhooks<br/>[webhooks.ts]"]
  node_ingest["Submission ingestion"]
  node_store[("Operational records<br/>[firestoreStore.ts]")]
  node_pubsub["Processing queue<br/>[pubsub.ts]"]
end

subgraph group_processing["Report processing"]
  node_worker["AI worker<br/>[app.ts]"]
  node_processor["Submission processing"]
  node_scoring["Issue scoring<br/>[scoring.ts]"]
end

subgraph group_government["Officer operations"]
  node_workflow["Issue workflow<br/>[workflow.ts]"]
  node_planner["Budget planner<br/>[planner.ts]"]
  node_projects["Projects and schemes<br/>[projects.ts]"]
end

subgraph group_insights["Insights and accountability"]
  node_insights_routes["Insight endpoints<br/>[insights.ts]"]
  node_insights_service["Forecast and equity<br/>[service.ts]"]
  node_bigquery[("Regional and investment data<br/>[bigquery.ts]")]
  node_public_routes["Public tracking and data<br/>[public.ts]"]
  node_confirmation["Citizen confirmation<br/>[issues.ts]"]
end

node_citizen(("Citizen"))
node_messaging(("WhatsApp / SMS"))
node_officer(("Public works officer"))

node_citizen -->|"files report"| node_web
node_citizen -->|"sends report"| node_messaging
node_web -->|"queues offline"| node_offline
node_offline -->|"replays report"| node_submission_routes
node_web -->|"uses API"| node_gateway_app
node_messaging -->|"posts message"| node_webhook_routes
node_gateway_app -->|"registers"| node_submission_routes
node_gateway_app -->|"registers"| node_webhook_routes
node_submission_routes -->|"ingests"| node_ingest
node_webhook_routes -->|"shared ingestion"| node_ingest
node_ingest -->|"writes submission"| node_store
node_ingest -->|"publishes event"| node_pubsub
node_pubsub -->|"delivers event"| node_worker
node_worker -->|"dispatches"| node_processor
node_worker -->|"runs scoring"| node_scoring
node_processor -->|"updates records"| node_store
node_scoring -->|"reads and scores issues"| node_store
node_officer -->|"uses console"| node_web
node_web -->|"manages issues"| node_workflow
node_web -->|"plans budgets"| node_planner
node_web -->|"manages projects"| node_projects
node_web -->|"views analysis"| node_insights_routes
node_insights_routes -->|"requests analysis"| node_insights_service
node_insights_service -->|"reads issue history"| node_store
node_insights_service -->|"reads investments"| node_bigquery
node_web -->|"tracks and explores"| node_public_routes
node_public_routes -->|"reads report status"| node_store
node_citizen -->|"confirms fix"| node_confirmation
node_confirmation -->|"records feedback"| node_store

click node_web "https://github.com/monolithic-dev/pramaan/blob/main/apps/web/src/App.tsx"
click node_offline "https://github.com/monolithic-dev/pramaan/blob/main/apps/web/src/hooks/useOfflineQueue.ts"
click node_gateway_app "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/app.ts"
click node_submission_routes "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/submissions.ts"
click node_webhook_routes "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/webhooks.ts"
click node_ingest "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/services/ingestSubmission.ts"
click node_store "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/store/firestoreStore.ts"
click node_pubsub "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/lib/pubsub.ts"
click node_worker "https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/app.ts"
click node_processor "https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/services/processSubmission.ts"
click node_scoring "https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/services/scoring.ts"
click node_workflow "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/workflow.ts"
click node_planner "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/services/planner.ts"
click node_projects "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/projects.ts"
click node_insights_routes "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/insights.ts"
click node_insights_service "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/insights/service.ts"
click node_bigquery "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/lib/bigquery.ts"
click node_public_routes "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/public.ts"
click node_confirmation "https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/issues.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_offline toneBlue
class node_gateway_app,node_submission_routes,node_webhook_routes,node_ingest,node_store,node_pubsub toneAmber
class node_worker,node_processor,node_scoring toneMint
class node_workflow,node_planner,node_projects toneRose
class node_insights_routes,node_insights_service,node_bigquery,node_public_routes,node_confirmation,node_citizen,node_messaging,node_officer toneIndigo
```

## Components

### Citizen channels

- [Citizen and officer app](https://github.com/monolithic-dev/pramaan/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Offline report queue](https://github.com/monolithic-dev/pramaan/blob/main/apps/web/src/hooks/useOfflineQueue.ts): `apps/web/src/hooks/useOfflineQueue.ts`

### API gateway

- [HTTP API](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/app.ts): `apps/api-gateway/src/app.ts`
- [Submission routes](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/submissions.ts): `apps/api-gateway/src/routes/submissions.ts`
- [Channel webhooks](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/webhooks.ts): `apps/api-gateway/src/routes/webhooks.ts`
- [Submission ingestion](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/services/ingestSubmission.ts): `apps/api-gateway/src/services/ingestSubmission.ts`
- [Operational records](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/store/firestoreStore.ts): `apps/api-gateway/src/store/firestoreStore.ts`
- [Processing queue](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/lib/pubsub.ts): `apps/api-gateway/src/lib/pubsub.ts`

### Report processing

- [AI worker](https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/app.ts): `apps/worker-ai-pipeline/src/app.ts`
- [Submission processing](https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/services/processSubmission.ts): `apps/worker-ai-pipeline/src/services/processSubmission.ts`
- [Issue scoring](https://github.com/monolithic-dev/pramaan/blob/main/apps/worker-ai-pipeline/src/services/scoring.ts): `apps/worker-ai-pipeline/src/services/scoring.ts`

### Officer operations

- [Issue workflow](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/workflow.ts): `apps/api-gateway/src/routes/workflow.ts`
- [Budget planner](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/services/planner.ts): `apps/api-gateway/src/services/planner.ts`
- [Projects and schemes](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/projects.ts): `apps/api-gateway/src/routes/projects.ts`

### Insights and accountability

- [Insight endpoints](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/insights.ts): `apps/api-gateway/src/routes/insights.ts`
- [Forecast and equity](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/insights/service.ts): `apps/api-gateway/src/insights/service.ts`
- [Regional and investment data](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/lib/bigquery.ts): `apps/api-gateway/src/lib/bigquery.ts`
- [Public tracking and data](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/public.ts): `apps/api-gateway/src/routes/public.ts`
- [Citizen confirmation](https://github.com/monolithic-dev/pramaan/blob/main/apps/api-gateway/src/routes/issues.ts): `apps/api-gateway/src/routes/issues.ts`

### Other components

- **Citizen**
- **WhatsApp / SMS**
- **Public works officer**

## Connections

- Citizen → Citizen and officer app: files report
- Citizen → WhatsApp / SMS: sends report
- Citizen and officer app → Offline report queue: queues offline
- Offline report queue → Submission routes: replays report
- Citizen and officer app → HTTP API: uses API
- WhatsApp / SMS → Channel webhooks: posts message
- HTTP API → Submission routes: registers
- HTTP API → Channel webhooks: registers
- Submission routes → Submission ingestion: ingests
- Channel webhooks → Submission ingestion: shared ingestion
- Submission ingestion → Operational records: writes submission
- Submission ingestion → Processing queue: publishes event
- Processing queue → AI worker: delivers event
- AI worker → Submission processing: dispatches
- AI worker → Issue scoring: runs scoring
- Submission processing → Operational records: updates records
- Issue scoring → Operational records: reads and scores issues
- Public works officer → Citizen and officer app: uses console
- Citizen and officer app → Issue workflow: manages issues
- Citizen and officer app → Budget planner: plans budgets
- Citizen and officer app → Projects and schemes: manages projects
- Citizen and officer app → Insight endpoints: views analysis
- Insight endpoints → Forecast and equity: requests analysis
- Forecast and equity → Operational records: reads issue history
- Forecast and equity → Regional and investment data: reads investments
- Citizen and officer app → Public tracking and data: tracks and explores
- Public tracking and data → Operational records: reads report status
- Citizen → Citizen confirmation: confirms fix
- Citizen confirmation → Operational records: records feedback