Principle:Langgenius Dify Node Composition
| Knowledge Sources | |
|---|---|
| Domains | Workflow Graph Composition DAG |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Node composition is the process of visually assembling a computational directed acyclic graph (DAG) through drag-and-drop placement of typed processing nodes and wiring them together with directional edges to define execution flow.
Description
The Dify visual workflow builder allows users to construct complex AI pipelines by composing individual processing nodes on a canvas. Each node represents a discrete computational step, and edges between nodes define the data flow and execution order. The composition process must ultimately be persisted to the server so that the workflow can be executed, shared, and versioned.
Node Types: The system supports a rich set of node types, each with a typed data payload:
- LLM -- Invokes a large language model with a prompt template and variable bindings
- Code -- Executes user-defined Python or JavaScript code
- HTTP Request -- Makes external API calls with configurable method, headers, and body
- Conditional (IF/ELSE) -- Branches execution based on evaluated conditions
- Iteration -- Loops over a list, executing a sub-graph for each element
- Loop -- Repeats a sub-graph until a condition is met or a limit is reached
- Start -- The entry point of the workflow, defining input variables
- End -- The terminal node that produces the final workflow output
- Trigger Plugin -- Initiates workflow execution from an external plugin event
- Knowledge Retrieval -- Queries vector stores for RAG-based context
- Question Classifier -- Routes execution based on intent classification
- Template Transform -- Applies Jinja2 templates to transform data
- Variable Aggregator -- Merges variables from multiple upstream branches
Edge Connections: Edges are directional links from a source node handle to a target node handle. They encode which node's output feeds into which node's input. The graph must remain acyclic to ensure deterministic execution ordering.
Payload Sanitization: Before the composed graph is sent to the server for persistence, the client performs sanitization to remove non-serializable or transient properties. This includes stripping underscore-prefixed temporary fields, normalizing node-specific data structures (e.g., ensuring json_schema fields on Start node variables are objects rather than strings), and sanitizing Trigger Plugin nodes to include only their defined schema fields.
Usage
Node composition is the primary activity in the Dify workflow studio. It is used whenever:
- A user creates a new workflow from scratch
- A user modifies an existing workflow by adding, removing, or reconnecting nodes
- The auto-save mechanism triggers to persist the current graph state
- A user duplicates or imports a workflow template
Theoretical Basis
Directed Acyclic Graph (DAG) Theory
Workflow composition is fundamentally the construction of a DAG. In graph theory, a DAG is a directed graph with no directed cycles, meaning there is no way to start at a vertex and follow a consistently directed sequence of edges that eventually loops back to the starting vertex.
Properties that the composition system must maintain:
- Acyclicity: Adding an edge must not create a cycle. The UI should validate this constraint during edge creation.
- Topological ordering: The nodes must admit at least one topological sort, which the execution engine uses to determine processing order.
- Typed connections: Not all output handles are compatible with all input handles. The type system constrains which connections are valid.
DAG Construction:
[Start] --> [LLM] --> [Conditional]
| \
v v
[Code] [HTTP Request]
| |
v v
[Variable Aggregator] --> [End]
Sanitization Pipeline
Before persistence, the graph passes through a sanitization pipeline:
User Canvas State
|
v
[ sanitizeWorkflowDraftPayload ]
|
|-- For each node:
| |-- sanitizeTriggerPluginNode (whitelist fields)
| |-- Normalize Start node json_schema (string -> object)
|
v
Sanitized Payload --> POST to Server
This ensures that the server receives a clean, canonical representation regardless of transient UI state that may have accumulated during editing.
Optimistic Concurrency
The composition system uses hash-based optimistic concurrency. Each save request includes the hash from the last known draft state. If another client has modified the draft in the interim, the server rejects the save, and the client must re-fetch and reconcile. The sync response returns an updated hash and timestamp for subsequent operations.