n8n Platform Overview
Relevant source files
The following files were used as context for generating this wiki page:
n8n is an extensible workflow automation platform that enables users to build and deploy AI agents and automated workflows. It utilizes a fair-code license model, allowing for both self-hosted deployments and cloud-based usage. The platform connects a visual building canvas with custom code capabilities, supporting over 1,500 integrations and native AI capabilities based on LangChain.
Sources: README.md:3-8, docker/images/n8n/README.md:3-6
Architecture and Monorepo Structure
n8n uses a monorepo structure managed by pnpm workspaces with Turbo build orchestration. The backend is built with Node.js and TypeScript using Express and TypeORM, while the frontend utilizes Vue 3 with Vite.
Sources: AGENTS.md:7-10, AGENTS.md:128-132, CONTRIBUTING.md:46-47
Core Modules
The platform is split into several functional modules located in the /packages directory:
| Module Path | Description |
|---|---|
packages/cli | Contains the Express server, REST API, and CLI commands for running the platform. |
packages/core | Handles the workflow execution engine, active webhooks, and internal logic. |
packages/workflow | Defines core workflow interfaces, types, and graph traversal utilities. |
packages/frontend/editor-ui | The Vue 3 application for the visual workflow editor. |
packages/nodes-base | Contains the built-in nodes for various service integrations. |
packages/@n8n/nodes-langchain | Dedicated nodes for AI and LangChain integration. |
Sources: CONTRIBUTING.md:52-65, AGENTS.md:143-154
The following diagram illustrates the relationship between the core modules during a typical workflow execution.
Workflow Engine and Nodes
Workflows in n8n are composed of "nodes," which serve as the basic building blocks. Nodes perform specific actions such as starting a workflow (Triggers), fetching data, or manipulating information.
Node Types
Nodes generally fall into three implementation categories:
- Programmatic Nodes: Use an
executefunction for custom logic (e.g., Discord). - Declarative Nodes: Use
requestDefaultsand routing configurations instead of manual execution logic (e.g., Okta). - Trigger Nodes: Start workflows based on external events, either via Webhooks or Polling.
Sources: packages/nodes-base/AGENTS.md:12-23, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:7-11
Node Components
A standard node implementation includes:
- Description: Metadata and UI configuration via the
INodeTypeDescriptioninterface. - Credentials: Entities that store sensitive connection information (e.g., API keys, OAuth tokens).
- Methods: Optional methods for dynamic UI elements like
loadOptions(dropdowns) orresourceMapping.
Sources: packages/nodes-base/AGENTS.md:7-10, packages/nodes-base/AGENTS.md:55-61, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:11-13
Data Flow and Persistence
n8n supports multiple database backends via TypeORM, primarily SQLite for local/default setups and PostgreSQL for production-grade environments.
Execution Flow
The following sequence diagram demonstrates how a workflow is triggered and executed:
Persistence Layer Guidelines
Business logic (services and controllers) must not directly import TypeORM operators. Instead, developers use use-case-named repository methods and a TransactionRunner provided by @n8n/db to manage units of work.
Sources: AGENTS.md:204-215
Deployment and Configuration
n8n is designed to be highly configurable through environment variables.
Key Environment Variables
| Variable | Purpose | Default / Example |
|---|---|---|
DB_TYPE | Specifies the database type. | sqlite or postgresdb |
N8N_PORT | Port the backend server listens on. | 5678 |
N8N_ENCRYPTION_KEY | Key used to encrypt sensitive credentials in the DB. | Generated at first start |
GENERIC_TIMEZONE | Timezone for nodes like the Schedule node. | Europe/Berlin |
N8N_USER_FOLDER | Location of the .n8n configuration folder. | ~/.n8n |
Sources: docker/images/n8n/README.md:62-67, docker/images/n8n/README.md:131-135, CONTRIBUTING.md:144-148
Security Boundary
The platform enforces a strict encryption boundary. Code must only encrypt or decrypt data through cipher.encryptV2() or cipher.decryptV2(). This ensures that key management is centralized and that sensitive data remains unreadable without the proper deployment keys.
Sources: AGENTS.md:247-254
Development Cycle
Development in the monorepo requires Node.js (v24+) and pnpm. The project uses a "stacked pull request" workflow for large changes and maintains strict linting through Biome and ESLint.
Essential Commands
pnpm install: Install and link all workspace modules.pnpm build: Compile all packages.pnpm start: Launch the production build.pnpm dev:be: Start the backend in development mode with hot-reloading.pnpm dev:fe:editor: Start the Vue frontend development server.
Sources: CONTRIBUTING.md:77-80, CONTRIBUTING.md:120-135, AGENTS.md:104-106
Summary
The n8n platform provides a modular, TypeScript-based architecture for workflow automation. By combining a flexible Node.js backend with a visual Vue.js frontend, it allows for complex integration logic through a system of extensible nodes. Its architecture emphasizes a clean separation between the persistence layer, the execution engine, and the visual editor, supported by a robust encryption framework for handling sensitive user credentials.
Sources: README.md:3-8, AGENTS.md:128-140