From c3143a8fd274b6303fe617c87f78fd9eb50a24fa Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Fri, 10 Jul 2026 12:51:23 +0200 Subject: [PATCH] chore: sync GovOPlaN module split state --- README.md | 10 +++ docs/CONCEPT.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 README.md create mode 100644 docs/CONCEPT.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc12c53 --- /dev/null +++ b/README.md @@ -0,0 +1,10 @@ +# govoplan-workflow + +`govoplan-workflow` will own process orchestration for GovOPlaN. + +The module should execute configurable state machines and command handoffs +between modules without importing their implementations. It coordinates cases, +tasks, forms, files, templates, mail, appointments, payments, and records +through capabilities, events, commands, and DTOs. + +See [docs/CONCEPT.md](docs/CONCEPT.md) for the current module concept. diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md new file mode 100644 index 0000000..84d1eda --- /dev/null +++ b/docs/CONCEPT.md @@ -0,0 +1,184 @@ +# 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.