# 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.