Workflow Builder (Visual Studio)

Document ID: DASH-002
File Path: docs/10-dashboard/workflow-builder.md
Version: 1.0.0
Status: Draft
Owner: AI Platform Team
Last Updated: 2026-06-27

1. Purpose

This document specifies the Workflow Builder — the visual studio for authoring, validating, and operating workflows without hand-writing YAML. It is a graphical front end over the Workflow DSL and the Workflows API.

1a. Implementation Status (v0.3)

The Angular dashboard (dashboard/) implements a working subset of this spec; the rest of the vision (§6, §8–§10, and the deeper §4/§5 items) is deferred.

Implemented:

Visual node canvas (features/workflow-builder/): a pan/zoom SVG canvas of draggable step nodes wired by bezier edges (transitions). Wiring is drag from a node’s output port onto another node’s input port; edges are click-to-remove.
Node palette + config: add steps of type Run a tool (function), Ask the model (ai), Run an agent (agent), Wait for approval (human), Wait for an event (wait). A per-node panel edits its id, type, tool/instructions/agent id/event, and inputs. function nodes pick their tool from a live catalog (GET /api/v1/tools — built-ins + enabled plugin tools); agent nodes pick a stored agent id from GET /api/v1/agents (agents created in Agent Studio), and run it end to end through the real model/tool loop rather than a bare chat call (see workflow-dsl.md §14a).
Canvas → DSL (one-way) generation to the DSL YAML, with a Generated YAML preview and an advanced raw-YAML mode toggle. (Full two-way canvas⇄DSL round-trip from arbitrary YAML — §2 — is not yet built; editing raw YAML doesn’t re-lay-out the canvas.)
Validate / Run / Observe: :validate shows the DAG; :run submits with an input form; an executions panel polls status, shows per-activity state, and offers signal/approve for waiting/human steps (§7, minus canvas animation).
Save / load: workflows (steps, wiring, and canvas layout) persist browser-local (localStorage) and reload onto the canvas. Durable, team-shared, RBAC-scoped, versioned persistence (§6, §9) is a later server-backed slice — workflow definitions aren’t yet stored server-side (only executions are).

Not yet implemented: HTTP/gRPC/script/timer/subprocess node types (§3, beyond function/ai/agent/human/wait), schema-driven input forms, expression autocomplete, versioning & diff (§6), templates/sub-workflow extraction (§8), collaboration/comments (§9), and accessibility affordances (§10).

2. Core Idea: Canvas ⇄ DSL

The builder maintains a two-way mapping between a visual graph and the DSL:

Canvas (nodes + edges)  ⇄  Workflow DSL (YAML/JSON)  ⇄  WIR (compiled graph)

Edits on the canvas update the DSL; editing the DSL updates the canvas.
The canonical artifact is the DSL; the canvas is a faithful rendering of it.
On save, the DSL is submitted to :validate → compiled to the WIR.

This guarantees the visual tool never produces a workflow the engine can’t run.

3. Node Palette

Nodes correspond to DSL activity types:

Node	DSL type
Function	`function`
HTTP / gRPC	`http` / `grpc`
AI Activity	`ai`
Tool	`tool`
Script	`script`
Human Task	`human`
Event Wait	`event`
Timer	`timer`
Sub-workflow	`subprocess`

Control-flow constructs (branch, parallel, loop) render as structural nodes mapping to DSL branches, parallel, and loops.

4. Authoring Features

Drag-and-drop nodes; connect with typed edges (transitions).
Per-node config panels with schema-driven forms (tool/AI inputs validated against their schemas from the Tools API).
Expression editor for conditions with autocomplete over workflow variables.
Inline retry/compensation/timeout configuration per node.
Variable and input definitions panel.

5. Live Validation

As the user edits, the builder surfaces the engine’s validation rules:

Unreachable nodes, orphaned transitions, duplicate IDs
Invalid expressions
Missing compensation mappings
Unresolved tool/permission references

Errors are shown on the offending node and in a problems panel before save.

6. Versioning & Diff

Saving creates a draft; publish produces an immutable workflow_version.
A visual diff compares two versions (added/removed/changed nodes and edges).
Running executions continue on their start version.

7. Run & Observe

From the builder a user can:

:run a workflow with an input form derived from its declared inputs.
Watch the execution animate on the canvas in real time — nodes highlight as they enter running, completed, failed, or compensating (execution stream).
Inspect per-node inputs/outputs, retries, and logs.
Complete human tasks inline.

8. Templates & Reuse

Start from templates (e.g. approval, RAG pipeline, ETL).
Extract a selection into a reusable sub-workflow.
Import/export DSL for version control and code review.

9. Collaboration

Comments on nodes.
Draft sharing within a project (RBAC-scoped).
Optimistic concurrency on save via ETag/If-Match; conflicting edits prompt a merge/reload.

10. Accessibility

The canvas supports keyboard-driven node creation/navigation and screen-reader labels for nodes and edges, in line with Overview §11.

11. Dependencies

13. Revision History

Version	Date	Description
1.0.0	2026-06-27	Initial Workflow Builder specification