$ cd architectures/n8n
·8 min read·v2.14.0

n8n Architecture

Workflow automation platform with 300+ integrations, native AI agent capabilities, and fair-code license — v2.14.0 monorepo (pnpm + Turborepo)

workflow-automationintegrationsai-agentslangchainfair-codemonorepo
View repository →
UI (Vue 3 / Vite)
Server / Engine
Database (TypeORM)
Nodes & Integrations
AI / LangChain
Config / Shared
CLI / Workers
External / Infra

System Layers

Frontend — Editor UI & Components
✎editor-uiVue 3 + Vite canvas editor
■design-systemShared Vue component library
💬chatEmbeddable chat widget
🔍codemirror-langExpression editor extensions
🌐i18nInternationalization strings
📦stores (Pinia)State management layer
Server — REST API, Webhooks & Orchestration
⚙cli (Server)Express app, controllers, REST API
🔗Webhookswebhook-server.ts, live & test
🔒AuthJWT + LDAP + SAML + MFA
📋LicenseFair-code & Enterprise gating
📣EventBusMessage event bus + log streaming
⚖PubSubRedis publisher/subscriber
Workflow Engine — Execution Core
⚡n8n-coreWorkflowExecute, node context, hooks
🔧n8n-workflowWorkflow model, expressions, graph
📊ActiveExecutionsIn-flight execution tracker
🔨ConcurrencyControlExecution slot limiter
⏳WaitTrackerDelayed execution resumption
🚀TaskRunnerSandboxed JS/Python code exec
Nodes — Integrations, Triggers & AI
🔌nodes-base300+ integration nodes
🤖nodes-langchainAI agents, chains, tools, memory
📥TriggersWebhook, Cron, Polling triggers
📦Community Nodesnpm-installed custom nodes
📚node-devNode development toolkit
🔧create-nodeCLI scaffolding for new nodes
Storage & Infrastructure
🗃@n8n/dbTypeORM entities, migrations, repos
🗃PostgreSQL / SQLitePrimary data store
⚡Redis (BullMQ)Job queue for worker scaling
📁Binary DataFilesystem / S3 binary storage
🔑External SecretsVault, AWS SM, Azure KV

Core Flow — Workflow Execution Lifecycle

1
Trigger fires — A webhook arrives, cron fires, or user clicks 'Execute' in the editor UI. The ActiveWorkflowManager detects the event.
↓
2
Execution created — WorkflowRunner creates an execution record, registers it in ActiveExecutions, and checks ConcurrencyControl for an available slot.
↓
3
Routing: local or queue — In main mode, execution runs in-process. In queue mode, ScalingService enqueues a BullMQ job to Redis for a worker to pick up.
↓
4
Graph traversal begins — WorkflowExecute.processRunExecutionData() walks the DAG, resolving connections and executing nodes in topological order with partial execution support.
↓
5
Node execution — Each node's execute() runs inside NodeExecutionContext. Code nodes run in the sandboxed TaskRunner. AI nodes invoke LangChain chains/agents.
↓
6
Data flows between nodes — Output items are passed along connections. Binary data is stored separately (filesystem/S3) with references in the execution data.
↓
7
Execution completes — ExecutionLifecycleHooks fire post-execution hooks. The run result (success/error) is persisted to the execution_entity table and pruned on schedule.

Authentication & Security Model

User Authentication
JWT tokens stored in n8n-auth HTTP-only cookie
Payload contains userId, password hash, browserId
MFA support via TOTP with MfaService
LDAP sync for enterprise directory integration
SAML SSO with AuthIdentity provider mapping
Role-based access: Owner, Admin, Member scopes
Project-level isolation with ProjectRelation entity
Invalid token revocation via InvalidAuthToken table
Credential Management
Credentials encrypted at rest with instance-level AES key
CredentialsEntity stores type, name, encrypted data
SharedCredentials controls project-level sharing
OAuth2 flow handled by client-oauth2 package
CredentialsOverwrites for env-var injection
External secrets: HashiCorp Vault, AWS SM, Azure KV
CredentialDependency tracks node-to-credential linkage
Credentials never exposed to frontend — resolved server-side only

Key Subsystem — Node & Trigger Architecture

packages/nodes-base/nodes/
├── Slack/                   ← 300+ service integration dirs
├── HttpRequest/             ← Generic HTTP node
├── Code/                    ← Custom JS/Python code execution
├── Webhook/                 ← Trigger: incoming HTTP webhooks
├── Cron/                    ← Trigger: scheduled execution

packages/@n8n/nodes-langchain/nodes/
├── agents/                  ← AI Agent node (ReAct, OpenAI Functions)
├── chains/                  ← LLM chains (summarization, QA, etc.)
├── tools/                   ← Agent tools (Calculator, Code, HTTP)
├── memory/                  ← Conversation memory (Buffer, Redis)
├── vector_store/            ← Pinecone, Qdrant, Supabase, PGVector
├── embeddings/              ← OpenAI, Cohere, HuggingFace embeddings
├── document_loaders/        ← PDF, CSV, web page loaders
├── llms/                    ← OpenAI, Anthropic, Ollama, etc.
├── output_parser/           ← Structured output & auto-fixing
├── mcp/                     ← Model Context Protocol server

packages/workflow/src/
├── expression.ts            ← {{ $json.field }} expression engine
├── graph/                   ← DAG traversal & connection resolution
├── node-parameters/         ← Parameter resolution & validation
Regular Nodes
execute() receives items, calls APIs, returns transformed items. 300+ integrations in nodes-base.
Trigger Nodes
Register webhooks or poll external services. ActiveWorkflowManager keeps them alive across restarts.
AI Agent Nodes
LangChain-based agents with tool use. Sub-nodes for memory, LLMs, vector stores connect via special ports.
Task Runner
Sandboxed execution environment for Code nodes. Separate process with JS and Python runtimes.
Expression Engine
Resolves {{ }} template expressions. Accesses $json, $input, $env with sandboxed evaluation.
Community Nodes
npm packages installed at runtime. Scanned and loaded by LoadNodesAndCredentials service.

Database Schema (TypeORM — PostgreSQL / SQLite)

workflow_entity
id, name, active, nodes (json), connections (json), settings, staticData, triggerCount
execution_entity
id, workflowId, status, mode, startedAt, stoppedAt, retryOf, retrySuccessId
execution_data
executionId (PK/FK), data (json) — full run data, workflowData (json)
credentials_entity
id, name, type, data (encrypted json), createdAt, updatedAt
user
id, email, firstName, lastName, password (bcrypt), role, disabled, mfaEnabled, mfaSecret
shared_workflow
workflowId, projectId, role (owner/editor/viewer), createdAt, updatedAt
shared_credentials
credentialsId, projectId, role (owner/user), createdAt, updatedAt
project
id, name, type (personal/team/public), icon, createdAt, updatedAt
project_relation
projectId, userId, role (admin/editor/viewer), createdAt, updatedAt
webhook_entity
webhookId, webhookPath, method, node, workflowId, pathLength
tag_entity
id, name, createdAt, updatedAt (M:M via workflow_tag_mapping)
variables
id, key, value, type — environment variables accessible via $vars
workflow_history
versionId, workflowId, nodes, connections, authors, createdAt
auth_identity
userId, providerId, providerType (saml/ldap), createdAt, updatedAt
settings
key, value (json), loadOnStartup (bool) — instance-wide config store
folder
id, name, parentFolderId, projectId, createdAt — hierarchical workflow grouping

Package / Directory Map

n8n-monorepo/                            pnpm workspaces + Turborepo
├── packages/cli/                        Main server: Express app, REST controllers, commands
│   ├── src/commands/start.ts            n8n start — boots server + UI
│   ├── src/commands/worker.ts           n8n worker — queue-mode job processor
│   ├── src/controllers/                 30+ REST API controllers
│   ├── src/scaling/                     BullMQ queue, PubSub, multi-main
│   ├── src/webhooks/                    Webhook server & request handling
│   ├── src/executions/                  Execution persistence & recovery
│   └── src/auth/                        JWT auth, LDAP, SAML handlers
│
├── packages/core/                       Execution engine: WorkflowExecute, node context
│   ├── src/execution-engine/            DAG walker, lifecycle hooks, partial exec
│   ├── src/nodes-loader/               Dynamic node & credential discovery
│   └── src/binary-data/                FS / S3 binary storage manager
│
├── packages/workflow/                   Workflow data model, expressions, graph
│   ├── src/expression.ts               {{ }} template expression evaluator
│   ├── src/graph/                      Node graph traversal algorithms
│   └── src/interfaces.ts               Core type definitions (INode, IWorkflow, etc.)
│
├── packages/nodes-base/                 300+ integration nodes (Slack, HTTP, etc.)
├── packages/@n8n/nodes-langchain/       AI nodes: agents, chains, LLMs, vector stores
├── packages/@n8n/db/                    TypeORM entities, migrations, repositories
├── packages/@n8n/task-runner/           Sandboxed JS/Python code execution process
├── packages/frontend/editor-ui/         Vue 3 workflow canvas editor (Vite)
├── packages/frontend/@n8n/design-system/ Shared Vue component library
├── packages/frontend/@n8n/chat/         Embeddable chat widget
├── packages/@n8n/config/                Typed configuration (class-based, env vars)
├── packages/@n8n/di/                    Dependency injection container
├── packages/@n8n/permissions/           RBAC scope definitions & checks
├── packages/@n8n/constants/             Shared constants across packages
├── packages/@n8n/benchmark/             Performance benchmarking suite
├── packages/@n8n/client-oauth2/         OAuth2 client library
└── packages/extensions/                 Expression helper functions
The Key Insight

n8n's power lies in its dual-mode execution engine — a single codebase serves both interactive editing (in-process) and production scaling (Redis + BullMQ worker queue), while the node abstraction unifies 300+ API integrations and LangChain-based AI agents behind one consistent interface: receive items, transform, return items. This makes every workflow node — from a simple HTTP call to a multi-step AI agent — composable on the same visual canvas.

← cd ../architectures