# keshavghatia/govflow-ai architecture

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

## Overview

GovFlow AI is an API-first government-request orchestration product: a citizen’s request becomes a tailored departmental workflow, advances through departmental systems, and is tracked for citizens and officers under an audit trail. The graph shows the documented workflow and major product surfaces. Some subsystems are documented but unsampled, so their internal links are omitted rather than inferred.

Main entry points: [`backend/app/services/intake.py`](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/intake.py) (Case intake), [`backend/app/services/executor.py`](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/executor.py) (Workflow execution), [`backend/app/api/webhooks.py`](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/webhooks.py) (Workflow callbacks), [`backend/app/services/audit.py`](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/audit.py) (Audit trail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_citizen_ui["Citizen experience<br/>[citizen.js]"]
  node_apply_ui["Application form<br/>[apply.js]"]
  node_demo_ui["Orchestration demo<br/>[demo.js]"]
  node_officer_ui["Officer dashboard<br/>[officer.js]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_api["API and intake"]
  node_cases_api["Cases API<br/>[cases.py]"]
  node_intake_api["Intake form API<br/>[intake_form.py]"]
  node_officer_api["Officer API<br/>[officer.py]"]
  node_webhooks_api["Workflow callbacks<br/>[webhooks.py]"]
  node_presenters["Response presenters<br/>[presenters.py]"]
end

subgraph group_workflow["Workflow intelligence"]
  node_intake["Case intake<br/>[intake.py]"]
  node_intent["Intent understanding<br/>[intent.py]"]
  node_composer["Dynamic composition<br/>[composer.py]"]
  node_executor["Workflow execution<br/>[executor.py]"]
  node_documents["Document processing<br/>[documents.py]"]
  node_automation["Workflow automation<br/>[automation.py]"]
  node_nba["Next best action<br/>[nba.py]"]
  node_risk["Risk assessment<br/>[risk.py]"]
end

subgraph group_governance["Governance and state"]
  node_sla["SLA tracking<br/>[sla.py]"]
  node_audit["Audit trail<br/>[audit.py]"]
  node_analytics["Analytics<br/>[analytics.py]"]
  node_domain_models["Case and workflow state<br/>[__init__.py]"]
  node_database[("Application database<br/>[db.py]")]
end

subgraph group_integrations["External systems"]
  node_adapters["Department adapters<br/>[__init__.py]"]
  node_departments["Department services A–G<br/>[main.py]"]
  node_workflow_engine["Workflow engine"]
  node_llm["Optional LLM service"]
end

node_citizen(("Citizen"))
node_officer_user(("Officer"))

node_citizen -->|"submits request"| node_citizen_ui
node_citizen -->|"enters application"| node_apply_ui
node_citizen -->|"runs demo"| node_demo_ui
node_officer_user -->|"reviews queue"| node_officer_ui
node_citizen_ui -->|"requests data"| node_frontend_api
node_officer_ui -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_cases_api
node_apply_ui -->|"submits form"| node_intake_api
node_demo_ui -->|"drives journey"| node_cases_api
node_cases_api -->|"creates cases"| node_intake
node_intake_api -->|"creates cases"| node_intake
node_officer_api -->|"advances steps"| node_executor
node_webhooks_api -->|"classifies requests"| node_intent
node_webhooks_api -->|"advances workflow"| node_executor
node_webhooks_api -->|"scores risk"| node_risk
node_intake -->|"understands goal"| node_intent
node_intake -->|"composes chain"| node_composer
node_intent -.->|"uses when enabled"| node_llm
node_composer -->|"fetches requirements"| node_adapters
node_executor -->|"calls departments"| node_adapters
node_adapters -->|"connects over HTTP"| node_departments
node_executor -->|"records events"| node_audit
node_executor -->|"reads clocks"| node_sla
node_automation -->|"dispatches events"| node_workflow_engine
node_workflow_engine -->|"calls callbacks"| node_webhooks_api
node_intake -->|"records consent and case"| node_audit
node_presenters -->|"presents actions"| node_nba
node_presenters -->|"presents clock state"| node_sla
node_audit -->|"writes audit entries"| node_domain_models
node_intake -->|"creates workflow state"| node_domain_models
node_domain_models -.->|"persists state"| node_database
node_documents -->|"records document events"| node_audit

click node_citizen_ui "https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/citizen.js"
click node_apply_ui "https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/apply.js"
click node_demo_ui "https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/demo.js"
click node_officer_ui "https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/officer.js"
click node_frontend_api "https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/api.js"
click node_cases_api "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/cases.py"
click node_intake_api "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/intake_form.py"
click node_officer_api "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/officer.py"
click node_webhooks_api "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/webhooks.py"
click node_presenters "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/presenters.py"
click node_intake "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/intake.py"
click node_intent "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/intent.py"
click node_composer "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/composer.py"
click node_executor "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/executor.py"
click node_documents "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/documents.py"
click node_automation "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/automation.py"
click node_nba "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/nba.py"
click node_risk "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/risk.py"
click node_sla "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/sla.py"
click node_audit "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/audit.py"
click node_analytics "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/analytics.py"
click node_domain_models "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/models/__init__.py"
click node_database "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/core/db.py"
click node_adapters "https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/adapters/__init__.py"
click node_departments "https://github.com/keshavghatia/govflow-ai/blob/main/mock-departments/app/main.py"

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_citizen_ui,node_apply_ui,node_demo_ui,node_officer_ui,node_frontend_api toneBlue
class node_cases_api,node_intake_api,node_officer_api,node_webhooks_api,node_presenters toneAmber
class node_intake,node_intent,node_composer,node_executor,node_documents,node_automation,node_nba,node_risk toneMint
class node_sla,node_audit,node_analytics,node_domain_models,node_database toneRose
class node_adapters,node_departments,node_workflow_engine,node_llm,node_citizen,node_officer_user toneIndigo
```

## Components

### User experience

- [Citizen experience](https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/citizen.js): `frontend/js/citizen.js`
- [Application form](https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/apply.js): `frontend/js/apply.js`
- [Orchestration demo](https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/demo.js): `frontend/js/demo.js`
- [Officer dashboard](https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/officer.js): `frontend/js/officer.js`
- [API client](https://github.com/keshavghatia/govflow-ai/blob/main/frontend/js/api.js): `frontend/js/api.js`

### API and intake

- [Cases API](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/cases.py): `backend/app/api/cases.py`
- [Intake form API](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/intake_form.py): `backend/app/api/intake_form.py`
- [Officer API](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/officer.py): `backend/app/api/officer.py`
- [Workflow callbacks](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/webhooks.py): `backend/app/api/webhooks.py`
- [Response presenters](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/api/presenters.py): `backend/app/api/presenters.py`

### Workflow intelligence

- [Case intake](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/intake.py): `backend/app/services/intake.py`
- [Intent understanding](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/intent.py): `backend/app/services/intent.py`
- [Dynamic composition](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/composer.py): `backend/app/services/composer.py`
- [Workflow execution](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/executor.py): `backend/app/services/executor.py`
- [Document processing](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/documents.py): `backend/app/services/documents.py`
- [Workflow automation](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/automation.py): `backend/app/services/automation.py`
- [Next best action](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/nba.py): `backend/app/services/nba.py`
- [Risk assessment](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/risk.py): `backend/app/services/risk.py`

### Governance and state

- [SLA tracking](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/sla.py): `backend/app/services/sla.py`
- [Audit trail](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`
- [Analytics](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/services/analytics.py): `backend/app/services/analytics.py`
- [Case and workflow state](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/models/__init__.py): `backend/app/models/__init__.py`
- [Application database](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/core/db.py): `backend/app/core/db.py`

### External systems

- [Department adapters](https://github.com/keshavghatia/govflow-ai/blob/main/backend/app/adapters/__init__.py): `backend/app/adapters/__init__.py`
- [Department services A–G](https://github.com/keshavghatia/govflow-ai/blob/main/mock-departments/app/main.py): `mock-departments/app/main.py`
- **Workflow engine**
- **Optional LLM service**

### Other components

- **Citizen**
- **Officer**

## Connections

- Citizen → Citizen experience: submits request (evidence: `README.md`)
- Citizen → Application form: enters application (evidence: `README.md`)
- Citizen → Orchestration demo: runs demo (evidence: `README.md`)
- Officer → Officer dashboard: reviews queue (evidence: `README.md`)
- Citizen experience → API client: requests data (evidence: `frontend/js/citizen.js`)
- Officer dashboard → API client: requests data (evidence: `frontend/js/officer.js`)
- API client → Cases API: calls API (evidence: `README.md`)
- Application form → Intake form API: submits form (evidence: `README.md`)
- Orchestration demo → Cases API: drives journey (evidence: `README.md`)
- Cases API → Case intake: creates cases (evidence: `backend/app/api/cases.py`)
- Intake form API → Case intake: creates cases (evidence: `backend/app/api/intake_form.py`)
- Officer API → Workflow execution: advances steps (evidence: `backend/app/api/officer.py`)
- Workflow callbacks → Intent understanding: classifies requests (evidence: `backend/app/api/webhooks.py`)
- Workflow callbacks → Workflow execution: advances workflow (evidence: `backend/app/api/webhooks.py`)
- Workflow callbacks → Risk assessment: scores risk (evidence: `backend/app/api/webhooks.py`)
- Case intake → Intent understanding: understands goal (evidence: `backend/app/services/intake.py`)
- Case intake → Dynamic composition: composes chain (evidence: `backend/app/services/intake.py`)
- Intent understanding → Optional LLM service: uses when enabled (evidence: `backend/app/services/intent.py`)
- Dynamic composition → Department adapters: fetches requirements (evidence: `backend/app/services/composer.py`)
- Workflow execution → Department adapters: calls departments (evidence: `backend/app/services/executor.py`)
- Department adapters → Department services A–G: connects over HTTP (evidence: `README.md`)
- Workflow execution → Audit trail: records events (evidence: `backend/app/services/executor.py`)
- Workflow execution → SLA tracking: reads clocks (evidence: `backend/app/services/executor.py`)
- Workflow automation → Workflow engine: dispatches events (evidence: `backend/app/services/automation.py`)
- Workflow engine → Workflow callbacks: calls callbacks (evidence: `backend/app/api/webhooks.py`)
- Case intake → Audit trail: records consent and case (evidence: `backend/app/services/intake.py`)
- Response presenters → Next best action: presents actions (evidence: `backend/app/api/presenters.py`)
- Response presenters → SLA tracking: presents clock state (evidence: `backend/app/api/presenters.py`)
- Audit trail → Case and workflow state: writes audit entries (evidence: `backend/app/services/audit.py`)
- Case intake → Case and workflow state: creates workflow state (evidence: `backend/app/services/intake.py`)
- Case and workflow state → Application database: persists state
- Document processing → Audit trail: records document events (evidence: `backend/app/services/documents.py`)
