# qaizar-master/govflow-sih-demo architecture

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

- Interactive diagram: https://gitdiagram.com/qaizar-master/govflow-sih-demo
- Repository: https://github.com/qaizar-master/govflow-sih-demo

## Overview

GovFlow is a prototype interoperability and workflow platform: citizens submit service applications and consent, GovFlow asynchronously verifies information across simulated departmental systems, and officers review and return decisions. Its distinct stages include identity binding, registry pre-fill, document and data validation, workflow orchestration, decision write-back, and audit/SLA monitoring. The graph also shows the API, connector framework, persistence, and web interfaces. Relationships use the excerpts, SOURCE INDEX references, or README; unsampled implementation details are represented only where documented.

Main entry points: [`packages/core/src/workflow/engine.ts`](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/workflow/engine.ts) (Workflow engine), [`packages/core/src/applications.ts`](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/applications.ts) (Application service), [`apps/web/app`](https://github.com/qaizar-master/govflow-sih-demo/tree/master/apps/web/app) (Citizen and staff UI), [`apps/api/src/app.ts`](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/app.ts) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Citizen and staff UI"]
  node_application_ui["Application views<br/>[application.tsx]"]
end

subgraph group_api["API and access"]
  node_api_app["Express API<br/>[app.ts]"]
  node_application_routes["Application routes<br/>[applications.ts]"]
  node_auth_routes["Authentication routes<br/>[auth.ts]"]
  node_access["Authentication and scoping<br/>[auth.ts]"]
end

subgraph group_workflow["Application workflow"]
  node_application_service["Application service<br/>[applications.ts]"]
  node_workflow_engine["Workflow engine<br/>[engine.ts]"]
  node_worker["Workflow worker<br/>[main.ts]"]
  node_prefill["Pre-fill and reconciliation"]
  node_documents["Document processing"]
  node_validation["Data validation"]
end

subgraph group_integration["Department integration"]
  node_connector_registry["Connector registry"]
  node_connector_sdk["Connector adapters"]
  node_mapping["Mappings and service forms<br/>[mapping.ts]"]
  node_departments["Simulated departments<br/>[server.ts]"]
  node_crosswalk["Identity crosswalk and SSO"]
end

subgraph group_platform["Platform services"]
  node_queue["Job queue<br/>[queue.ts]"]
  node_database[("PostgreSQL<br/>[db.ts]")]
  node_audit["Audit log<br/>[audit.ts]"]
  node_notifications["Notifications and exceptions<br/>[notifications.ts]"]
  node_sla["SLA and monitoring<br/>[sla.ts]"]
end

node_citizen(("Citizen"))
node_officer(("Review officer"))
node_admin(("Administrator"))

node_citizen -->|"uses"| node_web
node_officer -->|"uses"| node_web
node_admin -->|"uses"| node_web
node_web -->|"REST / JSON"| node_api_app
node_web -->|"renders"| node_application_ui
node_api_app -->|"mounts"| node_application_routes
node_api_app -->|"mounts"| node_auth_routes
node_application_routes -->|"checks access"| node_access
node_application_routes -->|"creates and reads"| node_application_service
node_auth_routes -->|"lists identifier links"| node_crosswalk
node_application_service -->|"starts and resumes"| node_workflow_engine
node_application_service -->|"reconciles"| node_prefill
node_application_service -->|"records actions"| node_audit
node_application_service -->|"notifies applicant"| node_notifications
node_application_service -->|"assesses SLA"| node_sla
node_worker -->|"runs workflow"| node_workflow_engine
node_workflow_engine -->|"enqueues steps"| node_queue
node_queue -->|"dispatches jobs"| node_worker
node_workflow_engine -->|"gets connectors"| node_connector_registry
node_workflow_engine -->|"resolves identifiers"| node_crosswalk
node_workflow_engine -->|"produces report"| node_validation
node_workflow_engine -->|"processes documents"| node_documents
node_workflow_engine -->|"notifies roles"| node_notifications
node_workflow_engine -->|"dispatches decisions"| node_connector_registry
node_connector_registry -->|"uses adapters"| node_connector_sdk
node_connector_sdk -->|"transforms fields"| node_mapping
node_connector_sdk -->|"connects to systems"| node_departments
node_crosswalk -->|"reads links"| node_database
node_prefill -->|"gets connectors"| node_connector_registry
node_prefill -->|"resolves identifiers"| node_crosswalk
node_application_service -->|"stores workflow state"| node_database
node_audit -->|"appends entries"| node_database
node_worker -->|"shares workflow state"| node_database
node_api_app -.->|"health and failure control"| node_departments

click node_web "https://github.com/qaizar-master/govflow-sih-demo/tree/master/apps/web/app"
click node_application_ui "https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/web/components/govflow/application.tsx"
click node_api_app "https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/app.ts"
click node_application_routes "https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/routes/applications.ts"
click node_auth_routes "https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/routes/auth.ts"
click node_access "https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/middleware/auth.ts"
click node_application_service "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/applications.ts"
click node_workflow_engine "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/workflow/engine.ts"
click node_worker "https://github.com/qaizar-master/govflow-sih-demo/blob/master/workers/workflow-worker/src/main.ts"
click node_prefill "https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/prefill"
click node_documents "https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/documents"
click node_validation "https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/validation"
click node_connector_registry "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/connector-registry.ts"
click node_connector_sdk "https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/connector-sdk/src"
click node_mapping "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/contracts/src/mapping.ts"
click node_departments "https://github.com/qaizar-master/govflow-sih-demo/blob/master/services/mock-departments/src/server.ts"
click node_crosswalk "https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/identity"
click node_queue "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/queue.ts"
click node_database "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/db.ts"
click node_audit "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/audit.ts"
click node_notifications "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/notifications.ts"
click node_sla "https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/sla.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_application_ui,node_officer toneBlue
class node_api_app,node_application_routes,node_auth_routes,node_access toneAmber
class node_application_service,node_workflow_engine,node_worker,node_prefill,node_documents,node_validation toneMint
class node_connector_registry,node_connector_sdk,node_mapping,node_departments,node_crosswalk toneRose
class node_queue,node_database,node_audit,node_notifications,node_sla,node_citizen,node_admin toneIndigo
```

## Components

### User experience

- [Citizen and staff UI](https://github.com/qaizar-master/govflow-sih-demo/tree/master/apps/web/app): `apps/web/app`
- [Application views](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/web/components/govflow/application.tsx): `apps/web/components/govflow/application.tsx`

### API and access

- [Express API](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Application routes](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/routes/applications.ts): `apps/api/src/routes/applications.ts`
- [Authentication routes](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Authentication and scoping](https://github.com/qaizar-master/govflow-sih-demo/blob/master/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`

### Application workflow

- [Application service](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/applications.ts): `packages/core/src/applications.ts`
- [Workflow engine](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/workflow/engine.ts): `packages/core/src/workflow/engine.ts`
- [Workflow worker](https://github.com/qaizar-master/govflow-sih-demo/blob/master/workers/workflow-worker/src/main.ts): `workers/workflow-worker/src/main.ts`
- [Pre-fill and reconciliation](https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/prefill): `packages/core/src/prefill`
- [Document processing](https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/documents): `packages/core/src/documents`
- [Data validation](https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/validation): `packages/core/src/validation`

### Department integration

- [Connector registry](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/connector-registry.ts): `packages/core/src/connector-registry.ts`
- [Connector adapters](https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/connector-sdk/src): `packages/connector-sdk/src`
- [Mappings and service forms](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/contracts/src/mapping.ts): `packages/contracts/src/mapping.ts`
- [Simulated departments](https://github.com/qaizar-master/govflow-sih-demo/blob/master/services/mock-departments/src/server.ts): `services/mock-departments/src/server.ts`
- [Identity crosswalk and SSO](https://github.com/qaizar-master/govflow-sih-demo/tree/master/packages/core/src/identity): `packages/core/src/identity`

### Platform services

- [Job queue](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/queue.ts): `packages/core/src/queue.ts`
- [PostgreSQL](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/db.ts): `packages/core/src/db.ts`
- [Audit log](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/audit.ts): `packages/core/src/audit.ts`
- [Notifications and exceptions](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/notifications.ts): `packages/core/src/notifications.ts`
- [SLA and monitoring](https://github.com/qaizar-master/govflow-sih-demo/blob/master/packages/core/src/sla.ts): `packages/core/src/sla.ts`

### Other components

- **Citizen**
- **Review officer**
- **Administrator**

## Connections

- Citizen → Citizen and staff UI: uses
- Review officer → Citizen and staff UI: uses
- Administrator → Citizen and staff UI: uses
- Citizen and staff UI → Express API: REST / JSON
- Citizen and staff UI → Application views: renders (evidence: `apps/web/components/govflow/application.tsx`)
- Express API → Application routes: mounts (evidence: `apps/api/src/app.ts`)
- Express API → Authentication routes: mounts (evidence: `apps/api/src/app.ts`)
- Application routes → Authentication and scoping: checks access (evidence: `apps/api/src/routes/applications.ts`)
- Application routes → Application service: creates and reads (evidence: `apps/api/src/routes/applications.ts`)
- Authentication routes → Identity crosswalk and SSO: lists identifier links (evidence: `apps/api/src/routes/auth.ts`)
- Application service → Workflow engine: starts and resumes (evidence: `packages/core/src/applications.ts`)
- Application service → Pre-fill and reconciliation: reconciles (evidence: `packages/core/src/applications.ts`)
- Application service → Audit log: records actions (evidence: `packages/core/src/applications.ts`)
- Application service → Notifications and exceptions: notifies applicant (evidence: `packages/core/src/applications.ts`)
- Application service → SLA and monitoring: assesses SLA (evidence: `packages/core/src/applications.ts`)
- Workflow worker → Workflow engine: runs workflow (evidence: `workers/workflow-worker/src/main.ts`)
- Workflow engine → Job queue: enqueues steps (evidence: `packages/core/src/workflow/engine.ts`)
- Job queue → Workflow worker: dispatches jobs
- Workflow engine → Connector registry: gets connectors (evidence: `packages/core/src/workflow/engine.ts`)
- Workflow engine → Identity crosswalk and SSO: resolves identifiers (evidence: `packages/core/src/workflow/engine.ts`)
- Workflow engine → Data validation: produces report (evidence: `packages/core/src/workflow/engine.ts`)
- Workflow engine → Document processing: processes documents (evidence: `packages/core/src/workflow/engine.ts`)
- Workflow engine → Notifications and exceptions: notifies roles (evidence: `packages/core/src/workflow/engine.ts`)
- Workflow engine → Connector registry: dispatches decisions (evidence: `packages/core/src/workflow/engine.ts`)
- Connector registry → Connector adapters: uses adapters (evidence: `packages/core/src/connector-registry.ts`)
- Connector adapters → Mappings and service forms: transforms fields (evidence: `packages/connector-sdk/src/base-connector.ts`)
- Connector adapters → Simulated departments: connects to systems
- Identity crosswalk and SSO → PostgreSQL: reads links (evidence: `packages/core/src/identity/crosswalk.ts`)
- Pre-fill and reconciliation → Connector registry: gets connectors (evidence: `packages/core/src/prefill/index.ts`)
- Pre-fill and reconciliation → Identity crosswalk and SSO: resolves identifiers (evidence: `packages/core/src/prefill/index.ts`)
- Application service → PostgreSQL: stores workflow state (evidence: `packages/core/src/applications.ts`)
- Audit log → PostgreSQL: appends entries (evidence: `packages/core/src/audit.ts`)
- Workflow worker → PostgreSQL: shares workflow state
- Express API → Simulated departments: health and failure control