Workflow Builder & Canvas
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
- packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts
- packages/cli/src/modules/instance-ai/instance-ai.adapter.service.ts
- packages/cli/src/modules/mcp/tools/workflow-builder/create-workflow-from-code.tool.ts
The Workflow Builder and Canvas system provides the interface and programmatic SDK for creating n8n automation workflows. This system represents workflows as directed graphs where nodes perform specific actions and connections define data flow.
The builder operates through two primary modes: a visual canvas for manual node placement and a programmatic Workflow SDK for code-based generation. The SDK utilizes a restricted subset of TypeScript to define static workflow graphs, which the execution engine later interprets.
Sources: packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:182-190, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:31-35
Workflow SDK Architecture
The Workflow SDK allows you to define workflows using fluent TypeScript methods. It is an Abstract Syntax Tree (AST) interpreted language, not an execution environment. The code describes the graph structure, which the server parses into a JSON format for persistence.
Core SDK Methods
| Method | Description |
|---|---|
workflow(id, name) | Initializes a new workflow instance with a unique ID and display name. |
.add(node) | Adds a node or trigger to the workflow graph. |
.to(node) | Creates a main connection from the previous node to the target node. |
.group(name, nodes) | Creates a visual frame (Node Group) around specified nodes. |
trigger(config) | Defines a starting point for the workflow (e.g., Webhook, Schedule). |
node(config) | Defines a processing step with specific parameters and position. |
Sources: packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:30-45, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:44-65
Programmatic Construction Flow
Programmatic building follows a specific tool-calling sequence to ensure valid graph generation.
The diagram shows the sequence of Model Context Protocol (MCP) tool calls required to build a workflow from a user request.
Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:89-115
Canvas Organization and Node Groups
Node groups provide visual structure to the canvas. While they have no execution semantics, they organize nodes into named frames to improve readability.
Grouping Rules and Constraints
- Unique Identity: Every group must have a unique name and ID within the workflow.
- Non-empty: A group must contain at least one node.
- Structural Boundaries: A group accepts exactly one entry member (receiving from outside) and one exit member (sending outside).
- Complexity Threshold: If a workflow contains more than 7 top-level items (nodes or groups), you must organize them into groups.
Sources: packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:98-115, packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:133-138
Group Selection Logic
The diagram illustrates the decision logic used by the builder to determine when and how to apply node groups on the canvas.
Sources: packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:133-145
Execution and Canvas Data
The Canvas displays real-time execution data by mapping internal execution results to visual nodes.
Data Extraction Patterns
The system extracts execution data from the database to render it on the canvas nodes. It performs smart truncation to prevent UI performance issues.
- Result Truncation: Total size is capped at 20,000 characters across all nodes.
- Node Preview: Individual node output previews are capped at 1,000 characters.
- Binary Markers: Nodes with binary output (files/images) are flagged on the canvas, but raw binary data is not sent to the primary builder context.
Sources: packages/cli/src/modules/instance-ai/instance-ai.adapter.service.ts:2080-2105, packages/cli/src/modules/instance-ai/instance-ai.adapter.service.ts:2210-2225
Execution Mode Selection
The builder determines the execution mode based on the trigger type present in the workflow:
| Trigger Type | Execution Mode |
|---|---|
webhook | webhook |
chatTrigger | chat |
scheduleTrigger / formTrigger | trigger |
| No Trigger / Manual | manual |
Sources: packages/cli/src/modules/instance-ai/instance-ai.adapter.service.ts:2620-2230
Validation and Persistence
Workflows must pass validation before the system persists them to the database.
Validation Layers
- SDK Syntax: The AST interpreter ensures the code uses allowed TypeScript constructs. Array methods like
.map()or.filter()are forbidden in builder code but allowed inside n8n expressions{{ }}. - Node Connection Validation: The system verifies that connections match allowed input/output types (e.g.,
main,ai_languageModel). - Credential Verification: The builder checks if the referenced credentials are reachable and valid for the target project.
Sources: packages/@n8n/workflow-sdk/src/prompts/sdk-reference/sdk-language.ts:182-200, packages/cli/src/modules/mcp/tools/workflow-builder/create-workflow-from-code.tool.ts:250-275
Persistence Procedure
If you are creating a workflow via code:
- Strip any import statements from the submitted code.
- Parse the code into a standard JSON workflow structure.
- Resolve webhook IDs and sanitize credential references.
- Drop invalid node groups that violate structural rules.
- Assign the workflow to a specific Project ID and Folder ID.
- Save the
WorkflowEntityto the database.
Sources: packages/cli/src/modules/mcp/tools/workflow-builder/create-workflow-from-code.tool.ts:210-245
Summary
The n8n Workflow Builder & Canvas combines a visual node-based editor with a programmatic TypeScript SDK. The system enforces strict organizational rules through node groups and validates every graph structure before persistence to ensure execution reliability. Data flow on the canvas is supported by a robust extraction layer that handles large datasets through intelligent truncation and character-capping.