/mrge-io/eval-n8n

Wiki directory

Browse AI-generated documentation for any repository.

Home

Relevant source files

The following files were used as context for generating this wiki page:

n8n is a fair-code, extendable workflow automation platform designed for technical teams. It combines a visual, node-based editor with the ability to write custom code (JavaScript/Python), add npm packages, and build custom integrations. This allows for the creation of powerful and flexible automations while maintaining full control over data and deployments, either through self-hosting or a cloud offering. The system is built on a TypeScript-based monorepo, featuring a Node.js backend and a Vue.js frontend.

The platform is designed to be highly extensible, allowing developers to create their own custom nodes and integrations. It supports AI-native workflows using LangChain, advanced permissioning, and enterprise features like SSO and air-gapped deployments. The core philosophy is to provide the flexibility of code with the speed of a no-code interface.

Sources: docker/images/n8n/README.md:3-9, CLAUDE.md:6-9, CONTRIBUTING.md:12-13

Architecture Overview

n8n utilizes a monorepo structure managed by pnpm workspaces and orchestrated with Turbo for building. This architecture separates concerns into distinct packages, facilitating independent development and maintenance.

Sources: CLAUDE.md:43, CONTRIBUTING.md:29-32

Package Structure

The monorepo is organized into several key packages that handle different aspects of the application, from core logic to UI components.

The diagram below illustrates the high-level relationship between the main packages.

Generating architecture diagram...

Package	Description
`packages/@n8n/api-types`	Contains shared TypeScript interfaces used for communication between the frontend and backend.
`packages/workflow`	Defines core workflow interfaces and types.
`packages/core`	The workflow execution engine.
`packages/cli`	Includes the Express server, REST API, and command-line interface commands.
`packages/editor-ui`	The Vue 3 frontend application for the workflow editor.
`@n8n/design-system`	A Vue component library that ensures UI consistency.
`packages/nodes-base`	Contains all built-in nodes for various integrations.
`@n8n/nodes-langchain`	Provides nodes specifically for AI and LangChain functionalities.
`@n8n/config`	Manages centralized configuration.

Sources: CLAUDE.md:48-58, CONTRIBUTING.md:17-27

Technology Stack

Category	Technologies
Frontend	Vue 3, TypeScript, Vite, Pinia, Storybook
Backend	Node.js, TypeScript, Express, TypeORM
Database	SQLite (default), PostgreSQL, MySQL
Testing	Jest (unit), Playwright (E2E), Vitest (frontend)
Code Quality	Biome (formatting), ESLint, lefthook git hooks

Sources: CLAUDE.md:60-65

Key Architectural Patterns

Dependency Injection: Uses @n8n/di for an Inversion of Control (IoC) container.
Controller-Service-Repository: The backend follows a pattern similar to MVC for organizing business logic.
Event-Driven: An internal event bus facilitates decoupled communication between different parts of the system.
Context-Based Execution: Different execution contexts are used for different types of nodes.
State Management: The frontend uses Pinia stores for managing application state.
Design System: Reusable Vue components and design tokens are centralized in @n8n/design-system.

Sources: CLAUDE.md:67-75

Core Concepts

The n8n platform revolves around workflows, which are composed of interconnected nodes that pass data to each other.

Workflows and Nodes

A workflow is a series of connected nodes that automate a process. Each node represents a specific action, such as reading a file, making an API call, or transforming data.

Trigger Nodes: These nodes start a workflow. They can be manual (e.g., Manual Trigger), run on a schedule (e.g., Cron), or listen for external events (e.g., Webhook).
Regular Nodes: These nodes perform actions like interacting with third-party services (HTTP Request, GitHub), manipulating data (Set), or controlling the flow of execution (IF, Switch).

The following diagram shows a simple workflow that receives an API request, processes the data, and responds.

Generating architecture diagram...

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json, packages/frontend/editor-ui/src/constants.ts:133, 160, 203

Expressions

Expressions are small JavaScript snippets enclosed in {{ }} that allow for dynamic data access and manipulation within node parameters. They are the "glue" that connects nodes by allowing one node to reference the output data of another.

Example Expression: {{ $('Source Data').item.json.name }}
This expression retrieves the name field from the JSON output of a node named "Source Data".

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json

Development

The repository is configured for a streamlined development experience, with tools for setup, building, testing, and creating new functionality.

Development Setup

To set up a local development environment, you need Node.js (v22.16+), pnpm (v10.2+), and standard build tools.

Fork and Clone: Fork the repository and clone it locally.
Install Dependencies: Run pnpm install in the root directory to install all dependencies and link the workspace packages.
Build Code: Run pnpm build to compile all packages.
Start Development Server: Use pnpm dev to start the backend and frontend with hot-reloading.

Sources: CONTRIBUTING.md:40-91

Essential Commands

The development workflow is managed through a series of pnpm scripts.

Command	Description
`pnpm build`	Builds all packages in the monorepo.
`pnpm dev`	Starts the full-stack development server with hot reload.
`pnpm dev:be`	Runs backend-only development mode.
`pnpm dev:fe`	Runs frontend-only development mode.
`pnpm test`	Runs all unit tests.
`pnpm lint`	Lints the code in the current package.
`pnpm typecheck`	Runs TypeScript type checks.

Sources: CLAUDE.md:15-39, CONTRIBUTING.md:93-146

Creating Custom Nodes

n8n can be extended with custom nodes. The @n8n/create-node package provides a scaffolding tool to quickly generate a new node project with a recommended structure.

Quick Start:

npm create @n8n/node@latest

This command initiates an interactive setup process to configure the new node. The generated project includes the necessary files for the node logic, credentials, and package configuration.

The typical structure for a new node project is as follows:

my-awesome-api-node/
├── src/
│   ├── nodes/
│   │   └── MyAwesomeApi/
│   │       ├── MyAwesomeApi.node.ts
│   │       └── MyAwesomeApi.node.json
│   └── credentials/
│       └── MyAwesomeApiAuth.credentials.ts
├── package.json
└── tsconfig.json

Sources: packages/@n8n/create-node/README.md:5-13, 115-126

Testing

The project uses Jest for backend unit tests and Playwright for end-to-end (E2E) tests. The old Cypress tests are being migrated to Playwright.

Sources: CLAUDE.md:120-124

E2E Testing Architecture

The Playwright test suite follows a four-layer architecture for UI testing to ensure separation of concerns and maintainability.

This diagram shows the hierarchical structure of the UI testing framework.

Generating architecture diagram...

Tests (*.spec.ts): Contain high-level, readable test scenarios that describe business logic.
Composables (*Composer.ts): Orchestrate complex, multi-page business workflows (e.g., creating and executing a workflow).
Page Objects (*Page.ts): Encapsulate UI interactions and element locators for a specific page.
BasePage: Provides common, reusable utility methods like clickByTestId.

An API testing layer also exists, which uses API service helpers to interact directly with the backend REST API for setting up test states or performing API-driven tests.

Sources: packages/testing/playwright/CONTRIBUTING.md:25-41, packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:104-114, packages/testing/playwright/tests/ui/39-projects.spec.ts:5-12

Deployment with Docker

n8n is distributed as a Docker image, which is the recommended way to run it in production.

To start n8n, you can use the following command:

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

This command starts n8n and makes it accessible at http://localhost:5678. It also creates a Docker volume named n8n_data and mounts it to /home/node/.n8n inside the container. This directory is crucial as it stores the SQLite database (for workflows and executions) and the encryption key for credentials.

Configuration

n8n can be configured using environment variables. For example, to use a PostgreSQL database instead of the default SQLite:

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -e DB_TYPE=postgresdb \
 -e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
 -e DB_POSTGRESDB_USER=<POSTGRES_USER> \
 -e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

Sources: docker/images/n8n/README.md:55-89

Home

Relevant source files

The following files were used as context for generating this wiki page:

Sources: docker/images/n8n/README.md:3-9, CLAUDE.md:6-9, CONTRIBUTING.md:12-13

Architecture Overview

Sources: CLAUDE.md:43, CONTRIBUTING.md:29-32

Package Structure

The monorepo is organized into several key packages that handle different aspects of the application, from core logic to UI components.

The diagram below illustrates the high-level relationship between the main packages.

Generating architecture diagram...

Package	Description
`packages/@n8n/api-types`	Contains shared TypeScript interfaces used for communication between the frontend and backend.
`packages/workflow`	Defines core workflow interfaces and types.
`packages/core`	The workflow execution engine.
`packages/cli`	Includes the Express server, REST API, and command-line interface commands.
`packages/editor-ui`	The Vue 3 frontend application for the workflow editor.
`@n8n/design-system`	A Vue component library that ensures UI consistency.
`packages/nodes-base`	Contains all built-in nodes for various integrations.
`@n8n/nodes-langchain`	Provides nodes specifically for AI and LangChain functionalities.
`@n8n/config`	Manages centralized configuration.

Sources: CLAUDE.md:48-58, CONTRIBUTING.md:17-27

Technology Stack

Category	Technologies
Frontend	Vue 3, TypeScript, Vite, Pinia, Storybook
Backend	Node.js, TypeScript, Express, TypeORM
Database	SQLite (default), PostgreSQL, MySQL
Testing	Jest (unit), Playwright (E2E), Vitest (frontend)
Code Quality	Biome (formatting), ESLint, lefthook git hooks

Sources: CLAUDE.md:60-65

Key Architectural Patterns

Dependency Injection: Uses @n8n/di for an Inversion of Control (IoC) container.
Controller-Service-Repository: The backend follows a pattern similar to MVC for organizing business logic.
Event-Driven: An internal event bus facilitates decoupled communication between different parts of the system.
Context-Based Execution: Different execution contexts are used for different types of nodes.
State Management: The frontend uses Pinia stores for managing application state.
Design System: Reusable Vue components and design tokens are centralized in @n8n/design-system.

Sources: CLAUDE.md:67-75

Core Concepts

The n8n platform revolves around workflows, which are composed of interconnected nodes that pass data to each other.

Workflows and Nodes

A workflow is a series of connected nodes that automate a process. Each node represents a specific action, such as reading a file, making an API call, or transforming data.

Trigger Nodes: These nodes start a workflow. They can be manual (e.g., Manual Trigger), run on a schedule (e.g., Cron), or listen for external events (e.g., Webhook).
Regular Nodes: These nodes perform actions like interacting with third-party services (HTTP Request, GitHub), manipulating data (Set), or controlling the flow of execution (IF, Switch).

The following diagram shows a simple workflow that receives an API request, processes the data, and responds.

Generating architecture diagram...

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json, packages/frontend/editor-ui/src/constants.ts:133, 160, 203

Expressions

Example Expression: {{ $('Source Data').item.json.name }}
This expression retrieves the name field from the JSON output of a node named "Source Data".

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json

Development

The repository is configured for a streamlined development experience, with tools for setup, building, testing, and creating new functionality.

Development Setup

To set up a local development environment, you need Node.js (v22.16+), pnpm (v10.2+), and standard build tools.

Fork and Clone: Fork the repository and clone it locally.
Install Dependencies: Run pnpm install in the root directory to install all dependencies and link the workspace packages.
Build Code: Run pnpm build to compile all packages.
Start Development Server: Use pnpm dev to start the backend and frontend with hot-reloading.

Sources: CONTRIBUTING.md:40-91

Essential Commands

The development workflow is managed through a series of pnpm scripts.

Command	Description
`pnpm build`	Builds all packages in the monorepo.
`pnpm dev`	Starts the full-stack development server with hot reload.
`pnpm dev:be`	Runs backend-only development mode.
`pnpm dev:fe`	Runs frontend-only development mode.
`pnpm test`	Runs all unit tests.
`pnpm lint`	Lints the code in the current package.
`pnpm typecheck`	Runs TypeScript type checks.

Sources: CLAUDE.md:15-39, CONTRIBUTING.md:93-146

Creating Custom Nodes

n8n can be extended with custom nodes. The @n8n/create-node package provides a scaffolding tool to quickly generate a new node project with a recommended structure.

Quick Start:

npm create @n8n/node@latest

This command initiates an interactive setup process to configure the new node. The generated project includes the necessary files for the node logic, credentials, and package configuration.

The typical structure for a new node project is as follows:

my-awesome-api-node/
├── src/
│   ├── nodes/
│   │   └── MyAwesomeApi/
│   │       ├── MyAwesomeApi.node.ts
│   │       └── MyAwesomeApi.node.json
│   └── credentials/
│       └── MyAwesomeApiAuth.credentials.ts
├── package.json
└── tsconfig.json

Sources: packages/@n8n/create-node/README.md:5-13, 115-126

Testing

The project uses Jest for backend unit tests and Playwright for end-to-end (E2E) tests. The old Cypress tests are being migrated to Playwright.

Sources: CLAUDE.md:120-124

E2E Testing Architecture

The Playwright test suite follows a four-layer architecture for UI testing to ensure separation of concerns and maintainability.

This diagram shows the hierarchical structure of the UI testing framework.

Generating architecture diagram...

Tests (*.spec.ts): Contain high-level, readable test scenarios that describe business logic.
Composables (*Composer.ts): Orchestrate complex, multi-page business workflows (e.g., creating and executing a workflow).
Page Objects (*Page.ts): Encapsulate UI interactions and element locators for a specific page.
BasePage: Provides common, reusable utility methods like clickByTestId.

An API testing layer also exists, which uses API service helpers to interact directly with the backend REST API for setting up test states or performing API-driven tests.

Sources: packages/testing/playwright/CONTRIBUTING.md:25-41, packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:104-114, packages/testing/playwright/tests/ui/39-projects.spec.ts:5-12

Deployment with Docker

n8n is distributed as a Docker image, which is the recommended way to run it in production.

To start n8n, you can use the following command:

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

Configuration

n8n can be configured using environment variables. For example, to use a PostgreSQL database instead of the default SQLite:

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -e DB_TYPE=postgresdb \
 -e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
 -e DB_POSTGRESDB_USER=<POSTGRES_USER> \
 -e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

Sources: docker/images/n8n/README.md:55-89