govoplan-workflow/docs/CONCEPT.md

govoplan-workflow Concept

Purpose

govoplan-workflow is the process orchestration module. It turns a configured administrative procedure into state transitions, guards, commands, timers, and operator-visible progress.

Workflow does not own business records. A case, task, file, appointment, template, payment, or postbox message remains owned by its domain module. Workflow coordinates those modules through stable contracts.

Workflow is also the first home for GovOPlaN's action/effect automation layer. That layer must keep automated actions governed, previewable, idempotent, auditable, and recoverable. If action catalogues, schedules, rule execution, or cross-module automation grow beyond workflow ownership, the runner can later be split into a dedicated govoplan-automation module without changing the action/effect contracts.

Ownership

The module owns:

• workflow definitions and versions
• workflow instances and current state
• transitions, guards, and transition history
• timers, deadlines, and wait states that belong to process execution
• command plans and command execution records
• retry/manual-intervention state for failed command handoffs
• action/effect execution records for workflow-triggered automation
• workflow audit/event emission
• workflow diagram metadata and WebUI route contributions

The module does not own:

• case records and case evidence
• task queues and task completion semantics
• form schemas or submissions
• file storage, documents, mail, notifications, appointments, payments, ledgers, or records
• external protocol adapters

Workflow Model

A workflow definition should contain:

• definition id, version, tenant scope, status
• states with labels, categories, and terminal markers
• transitions with from/to states, required scopes, guards, and commands
• input/output data schema references
• timers and escalation rules
• extension metadata for diagrams and operator UI

Instances should contain:

• instance id, tenant id, definition id/version
• subject references such as case_id or submission_id
• current state and previous state
• process variables with strict redaction rules
• transition history
• pending commands and manual actions

Core Contracts

The module should integrate through:

• module manifest metadata, route factories, permissions, and migrations
• events such as workflow.instance_started, workflow.transitioned, workflow.command_requested, workflow.command_failed, and workflow.instance_completed
• commands such as workflow.start, workflow.transition, workflow.retry_command, and workflow.cancel
• capability lookups for domain commands, for example cases, tasks, templates, appointments, and payments
• configuration-package fragments that install workflow definitions

Command handoff must be explicit. A transition should record which module capability was requested, with input payload, result summary, and failure reason.

The shared action/effect doctrine lives in govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md.

Reference Journey

Permit-to-payment MVP:

1. A form submission starts a workflow instance.
2. Workflow commands cases to create a case.
3. Workflow commands tasks to create an intake task.
4. Completion of the task transitions the instance to appointment proposal.
5. Appointment acceptance transitions to review/decision.
6. Workflow commands templates to generate a permit or decision.
7. Workflow commands payments/ledger handoff.
8. Workflow closes the case and emits evidence events.

MVP Slice

The first implementation should provide:

• static workflow definition registration from configuration packages
• create/read/list workflow instances
• transition execution with permission checks
• guard hooks implemented through capability calls
• command execution records with retry/manual-resolution state
• action/effect previews for transitions that call other modules
• idempotency keys for command execution
• explicit blocked, retryable, quarantined, manual-required, and compensation-required states
• basic WebUI instance detail and definition viewer
• dashboard summary provider
• event emission and audit integration

Permissions

Candidate scopes:

• workflow:definition:read
• workflow:definition:write
• workflow:instance:read
• workflow:instance:start
• workflow:instance:transition
• workflow:instance:admin

State transitions may require both workflow scopes and domain-module permission checks for the command being executed.

Workflow guard evaluation should consume access semantics through kernel capabilities instead of importing access internals:

• access.semanticDirectory resolves identity, account, organization unit, function assignment, delegation, and role facts.
• access.explanation records why a transition was allowed or denied in terms of identity/account/function/role/right provenance.

Transitions that allow a person to act in place of another function holder must require an explicit acting context and must record both the real actor account and the represented account/function assignment in transition history and audit details.

Data Model Sketch

Candidate tables:

• workflow_definitions
• workflow_definition_versions
• workflow_instances
• workflow_transition_history
• workflow_command_records
• workflow_timers

Definitions should be immutable by version after activation. Instances should reference the exact version used at start.

WebUI

Initial route contributions:

• /workflow
• /workflow/instances/:instanceId
• /workflow/definitions/:definitionId

The UI should show current state, available transitions, pending commands, failed handoffs, audit trace, and linked subject records. It should not import case/task/template components directly; panels are contributed through core UI extension points.

Tests

Minimum tests:

• core starts with workflow installed but cases/tasks/templates absent
• workflow definition versioning is immutable after activation
• transition guard denial is recorded and visible
• command failure is retryable and does not partially advance state
• events are emitted for start/transition/completion
• configuration package can install a simple workflow definition

Open Decisions

• Whether to implement BPMN import later or keep a GovOPlaN-native JSON model.
• How much visual workflow editing belongs in the first WebUI.
• Whether long-running timers use Celery beat, a module scheduler, or an ops scheduler abstraction.
• How workflow variables are redacted and retained.