Jeffrey Smith
81c28a50bf
All checks were successful
Co-authored-by: Jeffrey Smith <jasafpro@gmail.com> Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# Workflow Engine — Design
|
|
|
|
The workflow engine provides multi-stage, form-driven processes with team
|
|
validation, SLA enforcement, and public entry. Workflows are kernel primitives;
|
|
workflow **surfaces** (admin UI, public landing pages) are extension packages.
|
|
|
|
---
|
|
|
|
## Core Concepts
|
|
|
|
### Workflow Definition
|
|
|
|
A workflow is a named process template owned by a team. Each workflow defines an
|
|
ordered list of **stages** that instances progress through.
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `name` | Human-readable workflow name |
|
|
| `slug` | URL-safe identifier (unique per scope) |
|
|
| `scope` | Owning team or org |
|
|
| `stages` | Ordered list of stage definitions |
|
|
| `entry_mode` | `internal` (authenticated users) or `public_link` (landing page) |
|
|
| `sla_hours` | Optional SLA deadline for instance completion |
|
|
|
|
### Stage Types
|
|
|
|
Each stage has a `mode` that determines how participants interact:
|
|
|
|
| Mode | Behavior |
|
|
|------|----------|
|
|
| `form_only` | Structured form submission. Stage advances when form is complete. |
|
|
| `form_chat` | Form plus threaded discussion. Useful for review with comments. |
|
|
| `review` | Approval/rejection gate. Designated reviewers must sign off. |
|
|
| `custom` | Delegates entirely to a surface package. Enables extension-driven UIs. |
|
|
|
|
Stages declare an `assignee_mode` (individual, team, role-based) and optional
|
|
form schemas (JSON Schema validated at submission time).
|
|
|
|
### Workflow Instances
|
|
|
|
An instance is a running execution of a workflow definition. It tracks:
|
|
|
|
- Current stage index and overall status (`active`, `completed`, `cancelled`, `stale`)
|
|
- Per-stage completion records with timestamps and actor IDs
|
|
- Form data submitted at each stage
|
|
- Assignment and claim history
|
|
|
|
Instances use optimistic locking (`claimed_by` + `claimed_at`) to prevent
|
|
concurrent stage advancement. A claim expires after a configurable timeout.
|
|
|
|
---
|
|
|
|
## Multi-Party Validation (Signoff Table)
|
|
|
|
The `workflow_signoffs` table enables multi-party approval gates:
|
|
|
|
| Column | Purpose |
|
|
|--------|---------|
|
|
| `instance_id` | Which instance |
|
|
| `stage_index` | Which stage requires signoff |
|
|
| `user_id` | Who signed |
|
|
| `decision` | `approved` or `rejected` |
|
|
| `comment` | Optional rationale |
|
|
| `signed_at` | Timestamp |
|
|
|
|
The engine checks signoff requirements before advancing past a `review` stage.
|
|
Requirements are configurable: unanimous, majority, or N-of-M.
|
|
|
|
---
|
|
|
|
## SLA Scanner + Staleness Sweep
|
|
|
|
Two periodic background jobs maintain workflow health:
|
|
|
|
**SLA Scanner** — Runs on a configurable interval. Identifies instances that have
|
|
exceeded their workflow's `sla_hours` deadline. Fires a `workflow.sla.breached`
|
|
event (consumed by notification extensions or triggers).
|
|
|
|
**Staleness Sweep** — Identifies instances that have been idle (no stage
|
|
advancement) beyond a configurable threshold. Marks them as `stale` and fires
|
|
`workflow.instance.stale`. Stale instances can be resumed or cancelled.
|
|
|
|
Both jobs are distributed-safe: all cluster nodes run them, but operations are
|
|
idempotent (UPDATE with WHERE guards).
|
|
|
|
---
|
|
|
|
## Public Entry
|
|
|
|
Workflows with `entry_mode: public_link` are accessible at:
|
|
|
|
```
|
|
/w/:scope/:slug
|
|
```
|
|
|
|
The landing page renders the first stage's form without requiring authentication.
|
|
On submission, the kernel creates an instance and stores the form data. Subsequent
|
|
stages may require authentication depending on their assignee configuration.
|
|
|
|
Public entry enables use cases like intake forms, support requests, and
|
|
application submissions where the initiator is external.
|
|
|
|
---
|
|
|
|
## Extension Points
|
|
|
|
- **Surface packages** provide workflow admin UIs and participant views
|
|
- **Trigger extensions** can react to workflow events (`instance.created`,
|
|
`stage.advanced`, `sla.breached`, `instance.completed`)
|
|
- **Custom stage mode** delegates rendering and advancement logic entirely to
|
|
an extension, enabling arbitrary UIs within a workflow stage
|