> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Builder with Swim Lane Visualization — Integration

> Feature ID: PF-73 Status: ✅ Complete (Phase 1 + Phase 2 + Phase 3) — 2026-03-14 Spec Reference: PF-73-workflow-builder-swim-lane-visualization.md Last Updated:…

**Feature ID:** PF-73\
**Status:** ✅ Complete (Phase 1 + Phase 2 + Phase 3) — 2026-03-14\
**Spec Reference:** [PF-73-workflow-builder-swim-lane-visualization.md](../../../specs/pf/specs/PF-73-workflow-builder-swim-lane-visualization.md)\
**Last Updated:** 2026-03-14\
**Last Verified:** 2026-03-14

***

## Overview

PF-73 extends the Platform Workflow layer (`@/platform/workflow`) with swim lane diagram capabilities: horizontal/vertical lanes, node-in-lane placement, manual builder UI, policy/procedure-based generation (GR-01, GR-11), and AI-assisted generation (PF-27). Diagrams are stored in `pf_swim_lane_diagrams` and consumed by GR, FW, HR, and other cores for process documentation—**visualization only**, not workflow execution (FW-06 remains the execution engine).

***

## Quick Reference

| Item             | Value                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| Platform layer   | `@/platform/workflow` (extended by PF-73)                                        |
| Core table       | `pf_swim_lane_diagrams`                                                          |
| Key dependencies | PF-01, PF-02, PF-11, PF-27, PF-30, GR-01, GR-11, FW-06                           |
| Consumed by      | GR (procedures/policies), FW (documentation views), HR (onboarding/process docs) |
| Permissions      | `pf.swim-lane-diagrams.view`, `.create`, `.update`, `.delete`, `.export`         |
| SECURITY DEFINER | `pf_has_org_access(organization_id, auth.uid())` (or equivalent)                 |

***

## Integration Points (from Spec)

| Consumer | Usage                                                                                      | Phase Available |
| -------- | ------------------------------------------------------------------------------------------ | --------------- |
| GR       | Generate diagrams from GR-11 procedures and GR-01 policies; embed in procedure/policy docs | Phase 3         |
| FW       | Use swim lane component for workflow documentation views (optional)                        | Phase 4+        |
| HR       | Use swim lane component for onboarding/process documentation (optional)                    | Phase 4+        |
| Platform | Manual builder UI under platform routes; export to PF-11 documents                         | Phase 2–4       |

***

## API / Data Contracts

### Swim Lane Canvas & Types

**Import:** `import { SwimLaneCanvas, useSwimLaneDiagram, useSwimLaneDiagramList, useSwimLaneDiagramMutation } from '@/platform/workflow';`

**Types (PF-73):**

| Type                   | Description                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `LaneDefinition`       | `{ id: string; label: string; role?: string; department?: string; orientation: 'horizontal' \| 'vertical'; order: number; color?: string }` |
| `SwimLaneDiagramState` | `{ lanes: LaneDefinition[]; nodes: Node[]; edges: Edge[]; viewport?: { x: number; y: number; zoom: number } }`                              |
| Node `parentNodeId`    | When set, node is placed in the lane with that id; drag-between-lane updates this.                                                          |

**Hooks:**

| Hook                                               | Purpose                                                                              |
| -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `useSwimLaneDiagramList(organizationId, filters?)` | List diagrams; `.eq('organization_id', organizationId)`; staleTime/gcTime 5min/10min |
| `useSwimLaneDiagram(id)`                           | Single diagram; require orgId in query key                                           |
| `useSwimLaneDiagramMutation()`                     | Insert/update/delete with `.eq('organization_id', orgId)` on all mutations           |

**Component:**

* `SwimLaneCanvas` — Lane-aware canvas (group nodes or custom panels); lane CRUD, node palette, drag-between-lane, edges. Used by builder page and read-only view.

### Generation (Phase 3)

* **From procedure (GR-11):** Pass procedure id; platform reads `gr_procedures` and steps via allowed integration; returns diagram state with lanes derived from `responsible_role`. No direct core-to-core import; use platform or documented API.
* **From policy (GR-01) / AI:** Pass policy id or pasted text; **PHI validation required before calling PF-27/PF-62**; AI returns suggested lanes/steps; user confirms; diagram created with `source_type='policy'` or `'procedure'`.

### Export

* **PDF/PNG:** Use existing platform export utilities (e.g. `@/platform/forms` or document export). Permission: `pf.swim-lane-diagrams.export`.
* **Save as document:** Optional upload to PF-11 with title/folder; org-scoped.

***

## RLS Architecture

| Table                   | Scope            | SELECT                  | INSERT           | UPDATE                             | DELETE                  |
| ----------------------- | ---------------- | ----------------------- | ---------------- | ---------------------------------- | ----------------------- |
| `pf_swim_lane_diagrams` | organization\_id | SECURITY DEFINER helper | WITH CHECK (org) | USING + WITH CHECK (org unchanged) | SECURITY DEFINER helper |

**UPDATE policy:** MUST include `WITH CHECK` so `organization_id` cannot be changed (constitution §5.2.4). No RLS policy may query RLS-protected tables directly; use SECURITY DEFINER helpers only (§5.7).

***

## Realtime (Phase 2.2) — Channel and auth

Phase 2.2 collaborative realtime is **planned** (not yet implemented). The channel contract, presence/subscribe/broadcast semantics, and multi-tenant verification rules are documented in [EVENT\_CONTRACTS.md#pf-73-realtime-channel](./EVENT_CONTRACTS.md#pf-73-realtime-channel). When implemented, Supabase Realtime (broadcast/presence) MUST use the org-scoped channel and authorization-at-subscription-time rules defined there.

See also [PF-73 Phase 2 Expansion](../../../specs/pf/specs/PF-73-PHASE-2-EXPANSION.md) Integration Points for the full contract.

***

## Security and Tenant Isolation

* All access filtered by `organization_id`; RLS enforces org isolation.
* Mutations MUST include `.eq('organization_id', orgId)` (defense-in-depth).
* No PHI in diagram content or AI prompts; policy text sent to PF-27/PF-62 must pass pre-flight PHI validation.
* Permission keys: `pf.swim-lane-diagrams.view`, `.create`, `.update`, `.delete`, `.export`. All UI gated by these keys.

***

## Settings

| Setting                     | Table                | Default | Description                                           |
| --------------------------- | -------------------- | ------- | ----------------------------------------------------- |
| `swim_lane_builder_enabled` | `pf_module_settings` | true    | Enable/disable swim lane builder for the organization |

Migration must include CHECK (if applicable) and COMMENT ON COLUMN per constitution §5.2.5.

***

## Related Docs

* [PF-73 Spec](../../../specs/pf/specs/PF-73-workflow-builder-swim-lane-visualization.md)
* [PF-73 Plan](../../../specs/pf/plans/PF-73-workflow-builder-swim-lane-PLAN.md)
* [Platform Integration Layers](./PLATFORM_INTEGRATION_LAYERS.md)
* [GR-11 Procedures Management](../../../specs/gr/specs/GR-11-procedures-management.md)
* [FW-06 Advanced Workflow Builder](../../../specs/fw/archive/FW-06-advanced-workflow-builder.md)
* [Workflow Selection Guide](../../../docs/guides/use-cases/workflow-selection.md)
* [PF-73 Phase 2 Expansion](../../../specs/pf/specs/PF-73-PHASE-2-EXPANSION.md)

***

## Phase 2 API Contracts (added 2026-03-14)

### Version History (Phase 2.1)

**Import:** `import { useSwimLaneDiagramVersions, useCreateDiagramVersion } from '@/platform/workflow';`

| Hook                                           | Purpose                                                  |
| ---------------------------------------------- | -------------------------------------------------------- |
| `useSwimLaneDiagramVersions(orgId, diagramId)` | List version snapshots DESC; staleTime/gcTime 5min/10min |
| `useCreateDiagramVersion()`                    | Insert new version snapshot with auto-increment          |

**Component:** `DiagramVersionHistory` — Sheet-based panel with version list, read-only preview, and "Restore" action.

### Real-Time Collaboration (Phase 2.2)

**Import:** `import { useDiagramPresence, useDiagramBroadcast } from '@/platform/workflow';`

| Hook                                    | Purpose                                                |
| --------------------------------------- | ------------------------------------------------------ |
| `useDiagramPresence(orgId, diagramId)`  | Avatar stack of active users via `useRealtimePresence` |
| `useDiagramBroadcast(orgId, diagramId)` | Broadcast/receive `diagram_updated` events             |

**Channel:** `org:{orgId}:diagram:{diagramId}` — org-scoped per PF-66 standards.

### BPMN Import (Phase 2.3)

**Import:** `import { parseBpmnToSwimLane } from '@/platform/workflow';`

| Utility                            | Purpose                                                   |
| ---------------------------------- | --------------------------------------------------------- |
| `parseBpmnToSwimLane(xml: string)` | BPMN 2.0 XML → `SwimLaneDiagramState`; uses `bpmn-moddle` |

**Component:** `ImportBpmnDialog` — File picker + preview + import action.

### Templates Marketplace (Phase 2.4)

**Import:** `import { useSwimLaneTemplates } from '@/platform/workflow';`

| Hook                          | Purpose                              |
| ----------------------------- | ------------------------------------ |
| `useSwimLaneTemplates(orgId)` | List platform + org-scoped templates |

**Components:** `SwimLaneTemplateList`, `SwimLaneTemplatesPage`.\
**Route:** `/platform/workflows/diagrams/templates` (lazy-loaded, permission-gated).

***

## Phase 3 API — ✅ Complete (2026-03-14)

Phase 3 expansion ([PF-73-PHASE-3-EXPANSION.md](../../../specs/pf/specs/PF-73-PHASE-3-EXPANSION.md)) delivers:

### Hooks

| Hook                           | Import                | Purpose                                                        |
| ------------------------------ | --------------------- | -------------------------------------------------------------- |
| `useDiagramUndoRedo`           | `@/platform/workflow` | 50-step in-memory undo/redo stack; 400ms debounce              |
| `useWorkflowKeyboardShortcuts` | `@/platform/workflow` | Ctrl+Z/Y, Ctrl+C/V, Delete, zoom, fit view; disabled in inputs |

### Utilities

| Utility                                       | Import                | Purpose                                                                                                    |
| --------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `validateDiagram(nodes, edges)`               | `@/platform/workflow` | Structural validation: start/end events, orphan nodes, decision out-degree. Returns `{ errors, warnings }` |
| `serializeSwimLaneToBpmn(state)`              | `@/platform/workflow` | Export diagram as BPMN 2.0 XML; inverse of `parseBpmnToSwimLane`                                           |
| `getLayoutedDiagram(nodes, edges, direction)` | `@/platform/workflow` | Dagre-based auto-layout (TB/LR); preserves lane/group positions                                            |

### Components

| Component                | Purpose                                                      |
| ------------------------ | ------------------------------------------------------------ |
| `ShortcutHelpPanel`      | Dialog listing all keyboard shortcuts; opened via `?` or `K` |
| `DiagramValidationPanel` | Sheet showing errors/warnings with "Focus" node navigation   |

### BPMN Export Limitations

* Node positions are NOT preserved (no BPMNDI)
* Lane colors, orientation, and order are lost
* Node type information is lost on round-trip (parser assigns `type: 'default'`)
* Only `start`, `end`, `task`, `decision` types map to BPMN elements; others become `bpmn:task`

### Accessibility

* All node types have `role="img"` and `aria-label`
* `NodePalette` uses `role="toolbar"` with `aria-label`
* Canvas wrapped in `role="region"` with `aria-label`
* Keyboard shortcuts skip inputs/textareas/selects
* Visible focus rings on all interactive elements

### Dependency

* `@dagrejs/dagre` ^1.1.4 — auto-layout algorithm

### Testing

* **Unit tests:** `tests/unit/platform/workflow/` — diagramValidation (8), serializeSwimLaneToBpmn (5), dagreLayout (5), useDiagramUndoRedo (6)
* **Integration tests:** `tests/integration/platform/workflow/swim-lane-phase3.test.ts` — validate→export→reimport, layout→validate (4)