# ahmed252832/civic_app architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed252832/civic_app
- Repository: https://github.com/ahmed252832/civic_app

## Overview

CivicPulse Dhaka is a role-based complaint-management app for a Dhaka pilot area, offered as a hosted site and separate local web and Electron apps. Citizens register, submit and track reports; administrators verify, reject, identify duplicates, assign work and review analytics; assigned staff record progress; citizens can follow updates and provide feedback. The React client supports paged/searchable lists, case details and public maps. Backend variants share report and account logic, with distinct local-file and hosted Durable Object persistence. Major documented capabilities include administration, audit, encrypted backups and CSV export. Some feature wiring is documented in the README but absent from the sampled excerpts.

Main entry points: [`shared/store.cjs`](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs) (Domain store), [`src/api.ts`](https://github.com/ahmed252832/civic_app/blob/main/src/api.ts) (API client), [`src/App.tsx`](https://github.com/ahmed252832/civic_app/blob/main/src/App.tsx) (App interface), [`electron/database.cjs`](https://github.com/ahmed252832/civic_app/blob/main/electron/database.cjs) (Local SQLite adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["CivicPulse client"]
  node_react["App interface<br/>[App.tsx]"]
  node_maps["Maps and picker<br/>[MapViews.tsx]"]
  node_api["API client<br/>[api.ts]"]
  node_backup["Encrypted backup<br/>[backup.ts]"]
end

subgraph group_local["Local runtime"]
  node_localweb["Local web server<br/>[web.cjs]"]
  node_electron["Desktop IPC<br/>[main.cjs]"]
  node_localdb["Local SQLite adapter<br/>[database.cjs]"]
  node_localfile[("Local database file")]
end

subgraph group_hosted["Hosted runtime"]
  node_worker["Worker and API<br/>[worker.mjs]"]
  node_durable[("Dhaka Durable Object<br/>[worker.mjs]")]
end

subgraph group_domain["Complaint services"]
  node_store["Domain store<br/>[store.cjs]"]
  node_casework["Report lifecycle<br/>[store.cjs]"]
  node_access["Accounts and access<br/>[store.cjs]"]
  node_insights["Lists and analytics<br/>[store.cjs]"]
  node_governance["Administration and audit<br/>[store.cjs]"]
  node_archive["Backup and export<br/>[store.cjs]"]
end

node_citizens(("Citizens"))
node_administrators(("Administrators"))
node_staff(("Department staff"))
node_osm["OpenStreetMap tiles"]

node_citizens -->|"report and follow"| node_react
node_administrators -->|"verify and assign"| node_react
node_staff -->|"record progress"| node_react
node_react -->|"requests"| node_api
node_react -->|"renders locations"| node_maps
node_maps -.->|"loads tiles"| node_osm
node_api -->|"sends requests"| node_localweb
node_api -->|"dispatches IPC"| node_electron
node_api -->|"sends requests"| node_worker
node_backup -->|"pages and closes"| node_api
node_localweb -->|"creates database"| node_localdb
node_electron -->|"creates database"| node_localdb
node_localdb -->|"provides SQL operations"| node_store
node_localdb -->|"persists"| node_localfile
node_worker -->|"dispatches API"| node_durable
node_durable -->|"creates store"| node_store
node_store -->|"handles reports"| node_casework
node_store -->|"handles accounts"| node_access
node_store -->|"queries cases"| node_insights
node_store -->|"manages access and audit"| node_governance
node_store -->|"serves backup and export"| node_archive
node_backup -->|"collects pages"| node_archive

click node_react "https://github.com/ahmed252832/civic_app/blob/main/src/App.tsx"
click node_maps "https://github.com/ahmed252832/civic_app/blob/main/src/MapViews.tsx"
click node_api "https://github.com/ahmed252832/civic_app/blob/main/src/api.ts"
click node_backup "https://github.com/ahmed252832/civic_app/blob/main/src/backup.ts"
click node_localweb "https://github.com/ahmed252832/civic_app/blob/main/server/web.cjs"
click node_electron "https://github.com/ahmed252832/civic_app/blob/main/electron/main.cjs"
click node_localdb "https://github.com/ahmed252832/civic_app/blob/main/electron/database.cjs"
click node_worker "https://github.com/ahmed252832/civic_app/blob/main/cloudflare/worker.mjs"
click node_durable "https://github.com/ahmed252832/civic_app/blob/main/cloudflare/worker.mjs"
click node_store "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"
click node_casework "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"
click node_access "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"
click node_insights "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"
click node_governance "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"
click node_archive "https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs"

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_react,node_maps,node_api,node_backup toneBlue
class node_localweb,node_electron,node_localdb,node_localfile toneAmber
class node_worker,node_durable toneMint
class node_store,node_casework,node_access,node_insights,node_governance,node_archive toneRose
class node_citizens,node_administrators,node_staff,node_osm toneIndigo
```

## Components

### CivicPulse client

- [App interface](https://github.com/ahmed252832/civic_app/blob/main/src/App.tsx): `src/App.tsx`
- [Maps and picker](https://github.com/ahmed252832/civic_app/blob/main/src/MapViews.tsx): `src/MapViews.tsx`
- [API client](https://github.com/ahmed252832/civic_app/blob/main/src/api.ts): `src/api.ts`
- [Encrypted backup](https://github.com/ahmed252832/civic_app/blob/main/src/backup.ts): `src/backup.ts`

### Local runtime

- [Local web server](https://github.com/ahmed252832/civic_app/blob/main/server/web.cjs): `server/web.cjs`
- [Desktop IPC](https://github.com/ahmed252832/civic_app/blob/main/electron/main.cjs): `electron/main.cjs`
- [Local SQLite adapter](https://github.com/ahmed252832/civic_app/blob/main/electron/database.cjs): `electron/database.cjs`
- **Local database file**

### Hosted runtime

- [Worker and API](https://github.com/ahmed252832/civic_app/blob/main/cloudflare/worker.mjs): `cloudflare/worker.mjs`
- [Dhaka Durable Object](https://github.com/ahmed252832/civic_app/blob/main/cloudflare/worker.mjs): `cloudflare/worker.mjs`

### Complaint services

- [Domain store](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`
- [Report lifecycle](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`
- [Accounts and access](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`
- [Lists and analytics](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`
- [Administration and audit](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`
- [Backup and export](https://github.com/ahmed252832/civic_app/blob/main/shared/store.cjs): `shared/store.cjs`

### Other components

- **Citizens**
- **Administrators**
- **Department staff**
- **OpenStreetMap tiles**

## Connections

- Citizens → App interface: report and follow
- Administrators → App interface: verify and assign
- Department staff → App interface: record progress
- App interface → API client: requests
- App interface → Maps and picker: renders locations
- Maps and picker → OpenStreetMap tiles: loads tiles
- API client → Local web server: sends requests
- API client → Desktop IPC: dispatches IPC
- API client → Worker and API: sends requests
- Encrypted backup → API client: pages and closes
- Local web server → Local SQLite adapter: creates database
- Desktop IPC → Local SQLite adapter: creates database
- Local SQLite adapter → Domain store: provides SQL operations
- Local SQLite adapter → Local database file: persists
- Worker and API → Dhaka Durable Object: dispatches API
- Dhaka Durable Object → Domain store: creates store
- Domain store → Report lifecycle: handles reports
- Domain store → Accounts and access: handles accounts
- Domain store → Lists and analytics: queries cases
- Domain store → Administration and audit: manages access and audit
- Domain store → Backup and export: serves backup and export
- Encrypted backup → Backup and export: collects pages