n8n-io/n8n
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Executes custom workflows and AI agent automations with visual editor
Data enters through webhooks, manual triggers, or scheduled events, flows through connected nodes where each node transforms the INodeExecutionData payload, expressions evaluate against the flowing data, binary files are stored separately but referenced in the data stream, and results are returned to the trigger source or stored in the database. AI agents maintain conversation context in memory and use tools to interact with external systems.
Under the hood, the system uses 3 feedback loops, 4 data pools, 4 control points to manage its runtime behavior.
A 8-component fullstack. 11985 files analyzed. Data flows through 7 distinct pipeline stages.
How Data Flows Through the System
Data enters through webhooks, manual triggers, or scheduled events, flows through connected nodes where each node transforms the INodeExecutionData payload, expressions evaluate against the flowing data, binary files are stored separately but referenced in the data stream, and results are returned to the trigger source or stored in the database. AI agents maintain conversation context in memory and use tools to interact with external systems.
- Trigger Reception — WebhookServer receives HTTP requests, CronJob fires scheduled triggers, or ManualTrigger starts from UI — each creates initial INodeExecutionData with incoming payload and sets executionId
- Workflow Parsing — WorkflowRunner loads workflow definition from database, NodeTypes registry resolves node type implementations, ExpressionEvaluator initializes with workflow context and available data references [IWorkflowSettings → IWorkflow]
- Node Execution Sequence — WorkflowExecute processes nodes in dependency order, each node's execute() method receives INodeExecutionData array, transforms it using node-specific logic, and outputs modified INodeExecutionData [INodeExecutionData → INodeExecutionData]
- Expression Evaluation — ExpressionEvaluatorProxy runs sandboxed JavaScript expressions in node parameters, resolves $node() references to previous node data, evaluates $json expressions against current item data, returns computed values [INodeExecutionData → any (evaluated expression results)]
- Binary Data Handling — BinaryDataService stores file uploads to configured storage (filesystem/S3), creates IBinaryData references with metadata, maintains data-to-file mapping throughout execution [IBinaryData → IBinaryData]
- AI Agent Processing — Agent receives user messages, maintains conversation in ChatMemory, calls language models for planning, executes tools based on model decisions, accumulates results until goal completion [AgentMessage → AgentResult]
- Python Code Execution — Python Code node serializes TaskData to isolated task runner, TaskBrokerRpc executes user code in sandboxed environment with security restrictions, returns execution results or errors [TaskData → TaskResultData] (config: grant_token, task_broker_uri, max_concurrency +1)
Data Models
The data structures that flow between stages — the contracts that hold the system together.
packages/workflow/src/Interfaces.tsTypeScript interface with restApiUrl: string, instanceBaseUrl: string, webhookBaseUrl: string, executionId?: string, userId?: string, credentialsHelper: ICredentialsHelper
Created when workflow execution starts, passed through each node execution, provides context and credentials access
packages/workflow/src/Interfaces.tsTypeScript interface with json: IDataObject (key-value pairs), binary?: IBinaryKeyData (file attachments), pairedItem?: IPairedItemData (data lineage tracking)
Flows between connected nodes carrying the actual data payload, transformed by each node's processing logic
packages/workflow/src/Interfaces.tsTypeScript interface with executionOrder?: 'v0' | 'v1', saveManualExecutions?: boolean, callerPolicy?: string, errorWorkflow?: string
Defines workflow-level execution behavior, read once during workflow parsing and applied throughout execution
packages/@n8n/task-runner-python/src/message_types/broker.pyPython dataclass with code: str, node_mode: NodeMode, continue_on_fail: bool, items: Items, workflow_name: str, workflow_id: str, node_name: str, node_id: str, query: Query
Created when Python Code node executes, sent to isolated Python task runner, returns execution results
packages/@n8n/agents/src/types/message.tsTypeScript type with role: 'system' | 'user' | 'assistant' | 'tool', content: MessageContent[] (text, files, tool calls), metadata?: object
Represents conversation turns in AI agent workflows, accumulated in memory, used for context in model calls
packages/@n8n/ai-workflow-builder.ee/types/workflow.tsTypeScript interface with name: string, nodes: INode[], connections: IConnections, settings?: IWorkflowSettings, tags?: string[]
Generated by AI workflow builder, validated by binary checks, converted to full workflow schema for execution
Hidden Assumptions
Things this code relies on but never validates. These are the things that cause silent failures when the system changes.
INodeExecutionData flowing between workflow nodes contains a 'json' property that is a valid key-value object, with 'binary' and 'pairedItem' being optional — but there's no schema validation on the 'json' shape or depth limits
If this fails: If a malicious or buggy node outputs deeply nested objects, circular references, or non-serializable data in the 'json' field, downstream nodes will fail with stack overflow, JSON serialization errors, or memory exhaustion during workflow execution
packages/cli/src/WorkflowRunner.ts:WorkflowRunner
Binary files uploaded through IBinaryData can be stored and retrieved without size limits or disk space checks — the service assumes infinite storage capacity
If this fails: Large file uploads or workflows processing many files can fill the disk completely, causing the entire n8n instance to crash when attempting to save workflow states or binary data, with no graceful degradation
packages/core/src/binary-data/binary-data.service.ts:BinaryDataService
Python code in TaskData.code field is syntactically valid Python and doesn't contain infinite loops or memory bombs — the sandbox relies only on import restrictions and timeout
If this fails: User-provided Python code with syntax errors causes task runner crashes, while infinite loops consume CPU until timeout, and memory-intensive operations can exhaust system resources before the timeout triggers
packages/@n8n/task-runner-python/src/rpc/task_broker_rpc.py:TaskBrokerRpc
JavaScript expressions in node parameters referencing $node() data will always find existing node results, and that the referenced node data structure hasn't changed between expression compilation and evaluation
If this fails: If a workflow is modified while running, or if nodes are executed in unexpected order, expressions will access undefined properties or stale data, producing silent wrong results instead of clear errors
packages/workflow/src/Expression.ts:ExpressionEvaluatorProxy
Files specified in '_FILE' environment variables (like N8N_DB_PASSWORD_FILE) exist, are readable, and contain only the secret value without additional formatting or whitespace that matters for authentication
If this fails: If the file is missing, has wrong permissions, or contains extra whitespace, authentication with databases or external services will fail silently or with cryptic connection errors that don't point to the file issue
packages/cli/src/config/index.ts:config
AgentMessage array in conversation history maintains chronological order with alternating user/assistant roles, and that conversation context doesn't exceed the model's context window
If this fails: Out-of-order messages confuse the language model leading to nonsensical responses, while context overflow causes silent truncation of important conversation history, making agents forget previous tool results or user instructions
packages/@n8n/agents/src/sdk/agent.ts:Agent
Workflows have reasonable numbers of nodes (under 100) and connections — the execution engine doesn't have depth limits or cycle detection for node dependency resolution
If this fails: Workflows with hundreds of nodes or circular dependencies cause stack overflow during execution planning, while deeply nested subworkflow calls can exhaust memory without clear error messages about the architectural limits
packages/cli/src/WorkflowRunner.ts:WorkflowRunner
Server-sent event streams from AI providers follow standard SSE format with proper 'data:' prefixes and JSON payloads, and that streams don't contain malformed or incomplete JSON chunks
If this fails: Malformed SSE data from AI providers causes JSON parsing errors that crash AI agent workflows, while incomplete chunks result in hanging connections or corrupted tool call data that silently produces wrong automation results
packages/@n8n/ai-node-sdk/src/index.ts:parseSSEStream
Node type implementations loaded from the registry have execute() methods that return INodeExecutionData arrays with the same structure expected by downstream nodes — there's no interface validation at runtime
If this fails: Custom or third-party nodes that return malformed execution data cause type errors in subsequent nodes, leading to workflow failures that are difficult to debug since the error appears in the consumer node, not the producer
packages/workflow/src/NodeTypes.ts:NodeTypes
External systems being polled maintain consistent API responses and don't rate-limit or block polling requests — the polling interval is fixed regardless of external system behavior
If this fails: When external systems implement rate limiting or change their API responses, polling workflows fail repeatedly without backoff, potentially getting the n8n instance IP blocked, while API changes cause silent data parsing failures
packages/cli/src/ActiveWorkflows.ts:polling
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Stores workflow definitions, execution history, user credentials, and system settings in SQLite/PostgreSQL/MySQL
Persists uploaded files and generated attachments to filesystem or S3 with metadata tracking
Queues Python code execution requests for isolated task runners with concurrency limits
Maintains conversation history and context for AI agents across workflow executions
Feedback Loops
- Workflow Retry Loop (retry, balancing) — Trigger: Node execution failure with continueOnFail=false. Action: WorkflowRunner retries failed node with exponential backoff, preserves upstream data. Exit: Success, max retry count reached, or manual cancellation.
- Agent Planning Loop (recursive, reinforcing) — Trigger: Agent receives goal that requires multiple steps or tool usage. Action: Agent calls language model, executes suggested tools, adds results to conversation, repeats until goal achieved. Exit: Goal completion detected or max iteration limit reached.
- Expression Re-evaluation (cache-invalidation, balancing) — Trigger: Node parameter contains expression that references dynamic data. Action: ExpressionEvaluator re-computes expression value when referenced node data changes. Exit: Expression result stabilizes or execution completes.
Delays
- Binary Data Storage (async-processing, ~varies by file size and storage backend) — Node execution waits for file upload completion before proceeding
- Task Runner Initialization (warmup, ~1-3 seconds) — First Python code execution has startup overhead, subsequent calls are faster
- Workflow Polling (scheduled-job, ~configurable interval (default 60s)) — Polling triggers check external systems at regular intervals for new data
Control Points
- Execution Timeout (threshold) — Controls: Maximum time a workflow can run before forced termination. Default: task_timeout configuration parameter
- Python Security Sandbox (feature-flag) — Controls: Which Python modules and builtins are accessible in user code. Default: stdlib_allow, external_allow, builtins_deny sets
- AI Model Selection (architecture-switch) — Controls: Which language model provider and model to use for AI agent operations. Default: ModelConfig with provider and model name
- Binary Storage Backend (env-var) — Controls: Where files are stored (filesystem vs S3) and storage path configuration. Default: N8N_DEFAULT_BINARY_DATA_MODE environment variable
Technology Stack
Runtime environment for the main server application and workflow execution engine
Primary language for type safety across the large codebase with complex data flow
Frontend framework for the visual workflow editor with reactive component system
HTTP server framework handling REST API endpoints and webhook receivers
Database ORM for managing workflow storage, user data, and execution history
Configuration management with schema validation and environment variable support
AI framework for building agents with tool calling and memory management
Secondary runtime for user code execution in isolated task runner processes
Monorepo build orchestration managing dependencies between 61 packages
V8 isolate for secure expression evaluation without full Node.js context
Key Components
- WorkflowRunner (orchestrator) — Coordinates workflow execution by managing node sequence, handling data flow between nodes, and managing execution state transitions
packages/cli/src/WorkflowRunner.ts - NodeTypes (registry) — Maps node type names to their implementation classes, loads node definitions, and provides node metadata for the execution engine
packages/workflow/src/NodeTypes.ts - WorkflowExecute (processor) — Executes individual workflow nodes by calling their execute methods, handling input/output data transformation, and managing node-level errors
packages/workflow/src/WorkflowExecute.ts - ExpressionEvaluatorProxy (transformer) — Evaluates JavaScript expressions in node parameters using isolated VM, handles data references like $node and $json, and provides expression sandboxing
packages/workflow/src/Expression.ts - BinaryDataService (store) — Manages file storage for workflow attachments, handles binary data persistence to filesystem or S3, and provides data retrieval with metadata
packages/core/src/binary-data/binary-data.service.ts - Agent (orchestrator) — Coordinates AI agent execution by managing conversation flow, tool calling, memory persistence, and planning loops until goal completion
packages/@n8n/agents/src/sdk/agent.ts - TaskBrokerRpc (adapter) — Bridges n8n main process with isolated Python task runners using RPC over WebSockets, handles task distribution and result collection
packages/@n8n/task-runner-python/src/rpc/task_broker_rpc.py - CodeWorkflowBuilder (processor) — Generates complete workflows from natural language prompts using LLMs, validates generated node configurations, and handles iterative refinement
packages/@n8n/ai-workflow-builder.ee/src/code-builder/index.ts
Package Structure
Main server application that runs workflows, manages the database, handles webhooks, and provides the API for the frontend editor.
Core workflow execution engine that processes nodes, manages data flow, handles expressions, and defines the workflow schema.
Binary data handling, encryption utilities, and node execution runtime infrastructure.
Vue.js-based visual workflow editor with drag-and-drop node interface, expression editor, and workflow management UI.
Built-in integration nodes for 400+ services like HTTP requests, databases, cloud services, and AI platforms.
AI agent framework for building autonomous workflows using LangChain, tools, memory, and evaluation systems.
Shared utilities for AI nodes including chat models, memory management, vector stores, and LangChain integration.
Python code execution runtime that runs user Python code in isolated environments with security sandboxing.
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Fullstack Repositories
Frequently Asked Questions
What is n8n used for?
Executes custom workflows and AI agent automations with visual editor n8n-io/n8n is a 8-component fullstack written in TypeScript. Data flows through 7 distinct pipeline stages. The codebase contains 11985 files.
How is n8n architected?
n8n is organized into 5 architecture layers: Frontend Layer, API Layer, Execution Layer, Integration Layer, and 1 more. Data flows through 7 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through n8n?
Data moves through 7 stages: Trigger Reception → Workflow Parsing → Node Execution Sequence → Expression Evaluation → Binary Data Handling → .... Data enters through webhooks, manual triggers, or scheduled events, flows through connected nodes where each node transforms the INodeExecutionData payload, expressions evaluate against the flowing data, binary files are stored separately but referenced in the data stream, and results are returned to the trigger source or stored in the database. AI agents maintain conversation context in memory and use tools to interact with external systems. This pipeline design reflects a complex multi-stage processing system.
What technologies does n8n use?
The core stack includes Node.js (Runtime environment for the main server application and workflow execution engine), TypeScript (Primary language for type safety across the large codebase with complex data flow), Vue.js (Frontend framework for the visual workflow editor with reactive component system), Express.js (HTTP server framework handling REST API endpoints and webhook receivers), TypeORM (Database ORM for managing workflow storage, user data, and execution history), Convict (Configuration management with schema validation and environment variable support), and 4 more. This broad technology surface reflects a mature project with many integration points.
What system dynamics does n8n have?
n8n exhibits 4 data pools (Workflow Database, Binary Data Store), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle retry and recursive. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does n8n use?
5 design patterns detected: Plugin Architecture, Expression Language, Task Runner Isolation, AI Agent Framework, Fair-code Licensing.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.