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

# Swim Lane Diagrams

> Create, browse, and manage swim lane workflow diagrams; build or edit diagrams with multi-user presence, version history, and BPMN export.

The Swim Lane Diagrams page lists all workflow diagrams for your organization and provides entry points to create new diagrams, import BPMN files, and browse diagram templates. It is reached at `/platform/workflows/diagrams`.

## Overview

The page renders a data table of all diagrams owned by the organization, showing title, source type, status, version, and timestamps. From the header, users can:

* **New Diagram** — opens a guided creation wizard (`CreateDiagramWizard`).
* **Import BPMN** — opens `ImportBpmnDialog` to upload a `.bpmn` file.
* **Browse Templates** — navigates to `/platform/workflows/diagrams/templates`.
* **Generate from Policy / Procedure** — AI-assisted dialogs (`GenerateFromPolicyDialog`, `GenerateFromProcedureDialog`).

Clicking a diagram row navigates to the builder at `/platform/workflows/diagrams/:id`.

## Who it's for

Requires `pf.swim-lane-diagrams.view` (route guard). Creating diagrams additionally requires `pf.swim-lane-diagrams.create`.

## Before you start

* No prerequisites for viewing; your organization's diagrams load automatically.
* Creating diagrams requires `pf.swim-lane-diagrams.create`.

## Steps

1. Navigate to **Platform → Workflows → Diagrams** (`/platform/workflows/diagrams`).
2. Browse the table of existing diagrams.
3. Click a diagram row to open it in the builder.
4. To create a new diagram, click **New Diagram** and follow the wizard.
5. To use a pre-built template, click **Browse Templates**.

## Key concepts

**Source type** — indicates how the diagram was created: manually, via BPMN import, or via AI generation.

**Version** — each diagram tracks a version number, incremented on publish.

## Creating a diagram

Users with diagram creation permissions can start a new swim-lane diagram at `/platform/workflows/diagrams/new`. Requires `pf.swim-lane-diagrams.create`.

The New Diagram page launches the `SwimLaneDiagramBuilderPage`, a canvas-based editor built on `@xyflow/react`. The builder includes a node palette (`NodePalette`), lane management, undo/redo (`useDiagramUndoRedo`), live validation (`validateDiagram`, `DiagramValidationPanel`), version history sidebar (`DiagramVersionHistory`), real-time presence indicators (`useDiagramPresence`, `DiagramPresenceIndicator`), and export options including BPMN export (`ExportDiagramDropdown`). Diagrams can be saved as documents via `SaveAsDocumentDialog` and regenerated from procedure templates. The same component is reused for editing existing diagrams at `/platform/workflows/diagrams/:id` (requires `pf.swim-lane-diagrams.update`).

1. Navigate to **Platform > Workflows > Diagrams** and select **New Diagram** or go directly to `/platform/workflows/diagrams/new`.
2. Enter a name for the diagram.
3. Add lanes and nodes using the node palette on the left.
4. Connect nodes with edges to define the workflow path.
5. Use the validation panel to check for structural errors.
6. Save the diagram using the **Save** button. Use **Save as Document** to publish it to the document library.

**Swim lane** — A horizontal or vertical partition representing a participant, role, or system responsible for a set of activities in the workflow.

**Auto-layout** — The `getLayoutedDiagram()` utility can automatically reposition nodes for readability.

**BPMN export** — The export dropdown supports exporting the diagram in BPMN format for use with external process tools.

## Editing a diagram

The Edit Diagram page (`/platform/workflows/diagrams/:id`) is a full-featured visual editor supporting real-time collaborative editing with presence indicators, version history, auto-layout, BPMN export, and keyboard shortcuts. Requires `pf.swim-lane-diagrams.update`.

The page uses `ReactFlowProvider` and `SwimLaneCanvas` for the diagram canvas. It loads the diagram via `useSwimLaneDiagram` and uses `useSwimLaneDiagramMutation` for save operations. Supporting hooks: `useCreateDiagramVersion` (version history), `useDiagramPresence` (real-time collaborator presence via Supabase), `useDiagramBroadcast` (broadcast updates), and `useDiagramUndoRedo` (undo/redo stack). A validation panel via `validateDiagram` surfaces diagram errors. The toolbar offers save as template, auto-layout, horizontal/vertical layout modes, fullscreen, and BPMN export actions.

<Steps>
  <Step title="Open the diagram editor">
    Navigate to `/platform/workflows/diagrams/:id`. The canvas loads the saved diagram state.
  </Step>

  <Step title="Edit the diagram">
    Add, move, or remove lanes, nodes, and edges on the `SwimLaneCanvas`. Changes are tracked in the undo/redo stack.
  </Step>

  <Step title="Undo or redo changes">
    Use keyboard shortcuts or toolbar controls to undo or redo edits via `useDiagramUndoRedo`.
  </Step>

  <Step title="Validate the diagram">
    Open the validation panel to check for structural errors before saving.
  </Step>

  <Step title="Save the diagram">
    Click **Save** to persist the current state. Optionally, save as a template using the template action.
  </Step>

  <Step title="View version history">
    Open the version history sidebar to review or restore previous versions via `useCreateDiagramVersion`.
  </Step>

  <Step title="Export as BPMN">
    Use the BPMN export action to download the diagram in BPMN format.
  </Step>
</Steps>

**Presence indicators** — `useDiagramPresence` tracks which users are currently viewing or editing the diagram and broadcasts their cursor positions or states via Supabase Realtime.

**Version history** — `useCreateDiagramVersion` saves a snapshot on each explicit save. The version history sidebar allows reviewing and restoring prior versions.

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/workflow/pages/SwimLaneDiagramListPage.tsx
  * src/platform/workflow/hooks/useSwimLaneDiagramList.ts
  * src/platform/workflow/pages/SwimLaneDiagramBuilderPage.tsx
  * src/platform/workflow/hooks/useSwimLaneDiagram.ts
</Accordion>