n8n-core-architecture

Quick Reference

Architecture Layers (n8n v1.x)

Execution Modes (WorkflowExecuteMode)

Node Types

Critical Warnings

NEVER return a flat INodeExecutionData[] from execute() -- ALWAYS wrap in an outer array: return [returnData]. The outer array represents output indices (for multi-output nodes like IF/Switch).

NEVER mutate input items directly -- ALWAYS create new item objects. Mutating input items causes data corruption in downstream nodes that share the same reference.

NEVER ignore pairedItem in custom nodes that transform items -- ALWAYS set pairedItem: { item: i } to maintain item linking. Without paired items, n8n cannot trace data lineage.

NEVER assume item.binary exists -- ALWAYS check for undefined before accessing binary data. Not all items carry binary data.

NEVER use this.getNodeParameter('param', 0) with a hardcoded index when processing multiple items -- ALWAYS use the loop index i to get per-item parameter values.

NEVER skip continueOnFail() checks in custom nodes -- ALWAYS wrap item processing in try/catch and check this.continueOnFail() to respect user error settings.

Item-Based Execution Model

Data Flow

n8n processes data as items. Each node receives an array of items, processes them, and outputs an array of items:

Input: INodeExecutionData[]        →  Node  →  Output: INodeExecutionData[][]
[item0, item1, item2]                         [[result0, result1]]  (single output)
                                              [[trueItems], [falseItems]]  (two outputs)

INodeExecutionData Structure

interface INodeExecutionData {
    json: IDataObject;                    // REQUIRED - main data payload
    binary?: IBinaryKeyData;              // Optional file/binary data
    error?: NodeApiError | NodeOperationError;  // Error info if item errored
    pairedItem?: IPairedItemData | IPairedItemData[] | number;  // Item linking
    metadata?: {
        subExecution: RelatedExecution;   // Sub-workflow execution reference
    };
}

• json is the ONLY required field -- it contains the item's data as key-value pairs
• binary holds file data keyed by property name (e.g., "data", "attachment")
• pairedItem links output items back to their source input items
• error carries error details when an item fails processing

execute() Return Type

The return type INodeExecutionData[][] is a 2D array:

• First dimension: output index (output 0, output 1, etc.)
• Second dimension: items for that output

// Single output node (most common):
return [returnData];  // returnData is INodeExecutionData[]

// Two-output node (e.g., IF node):
return [trueItems, falseItems];

// Three-output node (e.g., Switch):
return [output0Items, output1Items, output2Items];

Binary Data

IBinaryData Structure

interface IBinaryData {
    data: string;          // Base64 encoded binary data (or reference ID)
    mimeType: string;      // MIME type (e.g., "image/png", "application/pdf")
    fileType?: BinaryFileType;  // 'text' | 'json' | 'image' | 'audio' | 'video' | 'pdf' | 'html'
    fileName?: string;
    fileExtension?: string;
    fileSize?: string;
    id?: string;           // Reference ID for filesystem-stored binary
}

IBinaryKeyData

Binary data on an item is stored as a keyed dictionary:

interface IBinaryKeyData {
    [key: string]: IBinaryData;  // e.g., { "data": {...}, "attachment": {...} }
}

ALWAYS access binary data through the key name: item.binary?.data or item.binary?.attachment.

Binary Helper Methods (in execute())

Paired Items

IPairedItemData Structure

interface IPairedItemData {
    item: number;          // Index of the source item in the input
    input?: number;        // Input index (default 0)
    sourceOverwrite?: ISourceData;  // Override source node
}

Setting Paired Items

ALWAYS set pairedItem when creating output items to maintain data lineage:

for (let i = 0; i < items.length; i++) {
    returnData.push({
        json: { /* processed data */ },
        pairedItem: { item: i },  // Links to input item at index i
    });
}

For items that map to multiple source items, use an array:

returnData.push({
    json: { /* aggregated data */ },
    pairedItem: [{ item: 0 }, { item: 1 }, { item: 2 }],
});

Process Modes

Single Process (Default)

• One Node.js process handles everything: webhooks, triggers, UI, and execution
• Suitable for low-volume workloads or development

Queue Mode (Production Scaling)

• Main process: Handles webhooks, triggers, and UI; enqueues execution jobs
• Worker processes: Dequeue and execute workflows independently
• Uses BullMQ (Redis-backed) for job queue management

Workflow Settings (IWorkflowSettings)

ALWAYS set executionOrder: 'v1' for new workflows -- v0 is legacy and produces non-deterministic execution order.

Expression Data Proxy

During execution, expressions have access to these variables:

$execution.customData

Store and retrieve custom metadata during execution:

$execution.customData.set("orderId", "12345");
$execution.customData.get("orderId");  // "12345"
$execution.customData.setAll({ key1: "val1", key2: "val2" });
$execution.customData.getAll();  // { key1: "val1", key2: "val2" }

Decision Trees

Choosing a Node Type

Need to START a workflow?
├── YES → Is it time-based?
│   ├── YES → Use trigger() with ITriggerFunctions (schedule trigger)
│   └── NO → Does it receive HTTP requests?
│       ├── YES → Use webhook() with IWebhookFunctions
│       └── NO → Does it poll an external service?
│           ├── YES → Use poll() with IPollFunctions (set polling: true)
│           └── NO → Use trigger() with custom event listener
└── NO → Is it a simple REST API wrapper?
    ├── YES → Use declarative node (routing config, no execute())
    └── NO → Use programmatic node with execute()

Choosing Process Mode

How many executions per day?
├── < 1000 → Single process (default)
├── 1000-10000 → Queue mode with 1-2 workers
└── > 10000 → Queue mode with multiple workers + Redis cluster

Reference Links

• references/methods.md -- INodeExecutionData, IBinaryData, IPairedItemData, IWorkflowSettings, WorkflowExecuteMode type signatures
• references/examples.md -- Item processing, binary data handling, paired items, workflow settings examples
• references/anti-patterns.md -- Data flow mistakes, item handling errors, common pitfalls

Official Sources

• https://docs.n8n.io/integrations/creating-nodes/
• https://docs.n8n.io/data/data-structure/
• https://docs.n8n.io/code/builtin/data-transformation-functions/
• https://github.com/n8n-io/n8n (packages/workflow/src/interfaces.ts)