Visual Builder Architecture
The Wardian Visual Builder provides a node-based interface for designing complex, multi-agent workflows. It translates a visual Directed Acyclic Graph (DAG) into the JSON-native WorkflowDefinition executed by the Rust backend.
🎨 The Canvas
Built on top of React Flow, the canvas provides a drag-and-drop environment for positioning nodes and defining execution paths (edges).
Type-Safe Port System
Nodes communicate via defined input and output ports. The visual builder enforces "type-safety" at the connection level:
- Ports are visually and logically distinguished (e.g.,
default,body,done,on_true,on_false). - This maps directly to the Transactional Consumption Logic used by the backend workflow engine.
🧠 Integrated Variable Assistant (IVA)
A standout feature of the Wardian Visual Builder is the Integrated Variable Assistant (IVA). Instead of requiring users to memorize the exact dot-notation paths of upstream node outputs, the IVA provides a contextual, interactive cheat sheet.
How it Works
The IVA is implemented as a React component (VariableAssistant.tsx) that sits alongside the canvas. When a node is selected, the IVA calculates the specific execution path leading up to that node and displays available variables.
1. Upstream Context Calculation
The IVA uses a custom hook (useUpstreamContext.ts) to traverse the graph backwards from the currently selected node. It identifies all upstream nodes whose outputs are guaranteed to be available in the Registry when the selected node executes.
2. Deep Key Extraction
The IVA inspects the JSON schemas or known output structures of the upstream nodes and generates a visual tree of available variables.
3. Cycle Awareness
For complex workflows involving loop nodes, the IVA distinguishes between:
- Upstream Outputs: Values generated in the current execution cycle.
- Cycle Contexts (PREV ITER): Values generated by nodes in a previous iteration of a loop, ensuring users don't accidentally reference stale data without intent.
4. One-Click Interpolation
Users can click any variable in the IVA tree (e.g., gatekeeper.decision). The IVA automatically wraps it in the correct Handlebars syntax (\{\{nodes.gatekeeper.output.decision\}\}) and copies it to the clipboard, ready to be pasted into prompt fields, file paths, or shell commands within the selected node's configuration.
Shared Storage
The IVA also constantly displays the storage.* namespace, allowing easy access to the persistent Key-Value store shared across all workflows and agents.