Welcome to n8n
Relevant source files
The following files were used as context for generating this wiki page:
n8n is a technical workflow automation platform designed to provide the flexibility of code combined with the speed of no-code interfaces. It is a technical tool that allows users to build complex automations using over 400 integrations, native AI capabilities, and a fair-code license model. The platform is built using a TypeScript monorepo architecture, utilizing a Node.js backend and a Vue.js frontend to enable extensible, node-based workflow orchestration.
Sources: README.md:3-7, AGENTS.md:5-7
The core of n8n revolves around "nodes"—the primary building blocks of a workflow. These nodes can act as triggers (starting a workflow), fetch/send data, or manipulate information. The system is designed for self-hosting or use via a cloud offering, emphasizing full control over data and deployments for technical teams.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:5-10, README.md:12-16
Core Architecture and Technology Stack
n8n is structured as a monorepo managed by pnpm workspaces and Turbo build orchestration. This modular approach allows for isolated build configurations while supporting cross-package dependencies.
Sources: AGENTS.md:5-7, AGENTS.md:65-67
Technology Stack Overview
| Component | Technology |
|---|---|
| Frontend | Vue 3, TypeScript, Vite, Pinia, Storybook |
| Backend | Node.js (v24+), TypeScript, Express, TypeORM |
| Database | SQLite (Default), PostgreSQL |
| Testing | Jest (Unit), Vitest (Frontend), Playwright (E2E) |
| Build Tools | pnpm, corepack, turbo, Biome |
Sources: CONTRIBUTING.md:64-70, AGENTS.md:86-90, AGENTS.md:144-149
Monorepo Structure
The project is split into several key packages located in the /packages directory:
@n8n/api-types: Shared TypeScript interfaces for frontend and backend communication.workflow: Core interfaces and types for the workflow engine.core: The engine responsible for workflow execution, webhooks, and active workflows.cli: Contains the Express server, REST API, and CLI command logic.editor-ui: The Vue 3 based graphical workflow editor.nodes-base: A collection of built-in nodes for various integrations.
Sources: CONTRIBUTING.md:31-42, AGENTS.md:71-84
Workflow Execution Logic
The platform operates on a node-based execution model where data flows from trigger nodes to action nodes.
The diagram above illustrates a high-level data flow where a trigger initiates the process, passing items through subsequent action nodes within the execution engine.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:5-10, AGENTS.md:105-110
Execution Rules
- Item-Based Processing: n8n executes each node once per input item. If a node outputs 10 items, the downstream node will run 10 times.
- Trigger Nodes: Special nodes that start a workflow based on external events (e.g., Webhooks) or scheduled intervals (e.g., Cron).
- Credential Management: Sensitive information for external APIs is stored in separate credential entities, which nodes reference during execution.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:5-12, CONTRIBUTING.md:34-36
Development Setup
The development environment requires specific tools and a sequence of commands to ensure the monorepo is correctly linked.
Prerequisites
- Node.js: Version 24 or newer.
- pnpm: Version 10.22 or newer (recommended via corepack).
- Build Tools:
build-essential(Linux),gcc-c++(CentOS), orwindows-build-tools(Windows).
Sources: CONTRIBUTING.md:64-89
Quick Start Commands
To set up a fresh development instance:
# 1. Install dependencies and link modules
pnpm install
# 2. Build all packages
pnpm build
# 3. Start the application
pnpm start
Sources: CONTRIBUTING.md:118-128, AGENTS.md:33-35
Development Workflow
Developers can run packages in different modes to save resources:
pnpm dev: Full stack development with hot reload.pnpm dev:be: Backend-only development.pnpm dev:fe: Frontend-only (Vue editor and design system) development.
Sources: CONTRIBUTING.md:144-165
Deployment and Hosting
n8n is designed to be self-hosted, primarily using Docker for ease of deployment.
The sequence diagram shows the startup flow where the n8n container loads essential configuration and keys from a persistent volume before accessing the database.
Sources: docker/images/n8n/README.md:46-56
Persistence Requirements
Regardless of the database type (SQLite or PostgreSQL), n8n requires the /home/node/.n8n folder to be persisted. This folder contains the encryption key used to secure credentials. If this key is lost, existing credentials cannot be decrypted.
Sources: docker/images/n8n/README.md:56-61, docker/images/n8n/README.md:73-77
Summary
n8n provides a robust, monorepo-based architecture for technical automation. By combining a Node.js backend with a modular node execution engine and a Vue-powered UI, it allows developers to build scalable workflows. The platform emphasizes developer control through its fair-code license, self-hosting capabilities, and a strict TypeScript-driven development cycle.
Sources: README.md:12-16, AGENTS.md:95-100, CONTRIBUTING.md:3-7