Introduction to n8n
Relevant source files
The following files were used as context for generating this wiki page:
n8n is a workflow automation platform that allows technical teams to build automations by connecting various nodes. It provides a visual interface for building workflows while supporting custom code in JavaScript and Python. The platform offers over 400 integrations and native AI capabilities based on LangChain. Sources: docker/images/n8n/README.md:3-8, AGENTS.md:7-9
The platform operates as an extensible node-based engine with a Node.js backend and a Vue.js frontend. Users can self-host the software or use a cloud-hosted version to maintain control over their data and deployments. Sources: docker/images/n8n/README.md:12-16, AGENTS.md:7-9
Core Architecture
n8n uses a monorepo structure managed by pnpm workspaces and Turbo build orchestration. The system divides functionality into isolated packages that handle different aspects of workflow execution, UI, and node logic. Sources: AGENTS.md:129-131, CONTRIBUTING.md:20-22
Package Structure
The following table summarizes the primary modules within the repository:
| Package | Purpose |
|---|---|
packages/cli | Express server, REST API, and CLI code for running the platform. |
packages/core | Core engine handling workflow execution, active webhooks, and logic. |
packages/workflow | Core interfaces and types used by both frontend and backend. |
packages/nodes-base | Built-in nodes providing standard integrations. |
packages/frontend/editor-ui | Vue 3 based workflow editor interface. |
packages/@n8n/api-types | Shared TypeScript interfaces for communication. |
Sources: CONTRIBUTING.md:24-38, AGENTS.md:133-146
System Components
The architecture follows a Controller-Service-Repository pattern on the backend and uses Pinia for state management on the frontend. The backend persists data using TypeORM with support for SQLite and PostgreSQL. Sources: AGENTS.md:154-162, docker/images/n8n/README.md:112-114
The diagram shows the relationship between the frontend interface, the API server, the core execution engine, and the data persistence layer. Sources: AGENTS.md:133-162, CONTRIBUTING.md:24-38
Workflow Engine and Nodes
Nodes serve as the basic building blocks of any workflow. There are two primary types of nodes: Trigger nodes, which start a workflow based on an event, and regular nodes, which fetch, send, or process data. Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:5-10
Node Implementation Types
Nodes are implemented using the INodeType interface and generally fall into one of two styles:
- Declarative Nodes: These use
requestDefaultsand routing configurations to define behavior through metadata rather than code. Sources: packages/nodes-base/AGENTS.md:16-17 - Programmatic Nodes: These implement an
execute()function containing custom logic for data processing. Sources: packages/nodes-base/AGENTS.md:14-15
Execution Flow
n8n executes each node once for every input item it receives. If a trigger or node outputs multiple items, all subsequent downstream nodes run once per item. Sources: packages/nodes-base/AGENTS.md:11-12
The sequence diagram illustrates the per-item execution logic where the engine iterates through data items for each node in the chain. Sources: packages/nodes-base/AGENTS.md:11-12
Data Persistence and Security
The persistence layer is restricted to the @n8n/typeorm boundary. Business logic must not import directly from TypeORM; instead, it uses repository methods to interact with data. Sources: AGENTS.md:189-195
Encryption Boundary
n8n enforces an encryption boundary to protect sensitive information such as credentials. All encryption and decryption must occur through cipher.encryptV2() and cipher.decryptV2(). Deployment keys are never deleted, as losing a key renders encrypted data unreadable. Sources: AGENTS.md:241-248
Database Configuration
While SQLite is the default for local installations, PostgreSQL is supported for production environments. Sensitive database configuration can be passed using environment variables or file-based secrets (appending _FILE to variable names). Sources: docker/images/n8n/README.md:112-133
Development and Scaffolding
The project provides specific CLI tools to facilitate the creation of custom "Community Nodes." These nodes allow developers to extend the platform's functionality and share integrations via npm. Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:10-14
- @n8n/node-cli: Used for building, linting, and developing nodes. Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:46-47
- n8n-node dev: Enables a file watcher and hot reloading for nodes by setting the
N8N_DEV_RELOAD=trueenvironment variable. Sources: CONTRIBUTING.md:150-155
Project Structure for Custom Nodes
Custom node packages follow a standard directory layout to be recognized by the platform:
.
├── nodes/
│ └── Example/
│ ├── Example.node.ts
│ └── Example.node.json
├── credentials/
│ └── Example.credentials.ts
└── package.json
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:21-30
Conclusion
n8n provides a modular and extensible architecture for workflow automation. By utilizing a monorepo structure, a strict encryption boundary, and a per-item execution model, the platform maintains a balance between developer flexibility and operational security. Developers can extend the core platform by creating custom nodes or by contributing to the shared TypeScript modules. Sources: AGENTS.md:7-12, CONTRIBUTING.md:20-22, packages/nodes-base/AGENTS.md:7-12