Source:
docs/manual/flow-builder.mdThis page is generated by
site/scripts/sync-manual-docs.mjs.
Visual Flow Builder
The visual flow builder is a drag-and-drop interface for designing graph workflows. It renders agent nodes, routing decisions, and data edges on a canvas, and exports the graph definition as JSON that can be submitted to the graph workflow engine.
Source: cmd/ui/frontend/src/components/flow/, cmd/ui/frontend/src/pages/FlowBuilderPage.tsx, internal/flow/
Overview
The Visual Flow Builder is a drag-and-drop workflow editor built with React Flow. It lets operators design agent workflows visually, mapping to the Graph DSL from internal/graph/. Flows are persisted as folders in a configurable GitHub repository, enabling version control, code review via PRs, and CI-friendly workflow management.
Node Types
The builder supports 8 node types corresponding to Graph DSL primitives:
| Node | Shape | DSL Mapping | Description |
|---|---|---|---|
| Start | Green circle | Entry point | Single output, marks workflow start |
| End | Red circle | Terminal | Single input, marks workflow end |
| Step | Rectangle | StepDef | Tool binding with optional condition |
| Route | Diamond | RouteDef | Conditional branching with cases + default |
| Parallel | Wide rectangle (fork) | ParallelDef | Concurrent branch execution |
| Join | Wide rectangle (merge) | JoinDef | Branch convergence (All/Any/N/Vote) |
| Subgraph | Dashed rectangle | SubgraphRef | Reference to another flow |
| Approval | Hexagon | InterruptDef | Human approval gate with timeout |
Building a Flow
Adding nodes
Drag nodes from the left palette onto the canvas. Nodes snap to a grid for alignment.
Connecting nodes
Click and drag from a node's output handle (bottom) to another node's input handle (top) to create an edge.
Configuring nodes
Click a node to select it. The property panel appears on the right with type-specific configuration:
- Step: name, tool binding (searchable dropdown), condition expression
- Route: case labels and expressions, default case toggle
- Parallel: branch names
- Join: join type (All/Any/N/Vote), N value for JoinN
- Approval: approval name, timeout duration
Validation
The builder validates the flow in real-time as you build:
- Missing start node (error)
- Parallel without matching join (error)
- Cycle detected (error)
- Unreachable nodes (warning)
- Route without default case (warning)
- Step without tool binding (warning)
Errors appear as badges on affected nodes and in the error panel at the bottom.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+Z | Undo |
| Ctrl+Shift+Z | Redo |
| Ctrl+S | Save draft |
| Delete / Backspace | Remove selected |
| Ctrl+A | Select all |
| Escape | Deselect all |
GitHub Persistence
Flows are stored in a configurable GitHub repository. Each flow is a folder containing:
<repo>/<flow-name>/
workflow.json # Graph DSL definition
metadata.json # Name, version, author, timestamps, layout positions
README.md # Auto-generated documentation
Commit modes
- Direct commit: saves directly to the configured branch
- PR mode: creates a new branch and opens a pull request for review
Loading flows
The Flow List page (/flows) shows all flows from the GitHub repository. Click a flow to open it in the builder.
History
View commit history for any flow. Click a past commit to load that version.
Preview / Dry-Run
The Preview feature executes the flow with mock tools to visualize the execution path:
- Completed nodes show a green border
- Failed nodes show a red border
- Skipped nodes are dimmed
- Active edges are animated
Use "Step Through" mode to advance one node at a time.
Deploy
Admin users can deploy a flow to register it as a new graph version in the tool registry. The flow must pass server-side validation before deployment.
Configuration
| Variable | Default | Description |
|---|---|---|
CRUVERO_FLOW_GITHUB_REPO | — | GitHub repo (org/repo format) |
CRUVERO_FLOW_GITHUB_BRANCH | main | Default branch |
CRUVERO_FLOW_GITHUB_TOKEN | — | GitHub PAT (falls back to GITHUB_TOKEN) |
CRUVERO_FLOW_GITHUB_PR_MODE | false | Create PRs instead of direct commits |
Roles
- Editor: Create, edit, save, and commit flows
- Admin: Deploy flows (register as graph versions)