High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:- AGENTS.md
- CONTRIBUTING.md
- packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-transformation.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/knowledge-base.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts
- packages/@n8n/create-node/README.md
- packages/nodes-base/AGENTS.md
- packages/nodes-base/TESTING_PROMPT.md
- packages/nodes-base/nodes/Webhook/Webhook.node.json
- packages/testing/playwright/AI-TEST-CHEAT-SHEET.md
- packages/testing/playwright/CONTRIBUTING.md
- packages/testing/playwright/tests/ui/29-templates.spec.ts
n8n is a workflow automation platform built with a TypeScript-based monorepo architecture. It features a Node.js backend with an Express server, a Vue.js frontend, and an extensible node-based workflow engine. The system is designed for modularity, allowing for independent development and deployment of its various components, such as the core execution engine, UI, and the extensive library of integration nodes.
The architecture emphasizes separation of concerns, with distinct packages for API types, core logic, UI components, and nodes. This structure is managed by pnpm workspaces and orchestrated by Turbo for efficient builds. Key architectural patterns include dependency injection, an event-driven internal bus, and a controller-service-repository pattern for the backend.
Sources: AGENTS.md:5-9, CONTRIBUTING.md:20-33
Monorepo and Package Structure
The n8n project is organized as a monorepo using pnpm workspaces. This structure facilitates code sharing, dependency management, and streamlined development across multiple related packages.
Sources: AGENTS.md:40-42, CONTRIBUTING.md:24-26
The diagram below illustrates the high-level relationship between the key packages in the monorepo.
This diagram shows the dependency flow between major packages within the n8n monorepo.
Sources: AGENTS.md:45-56, CONTRIBUTING.md:20-33
Key Packages
The monorepo contains several critical packages, each with a specific responsibility:
| Package | Description |
|---|---|
packages/cli | Contains the Express server, REST API, and Command Line Interface (CLI) commands for running the n8n backend. |
packages/core | The core workflow execution engine. It handles the processing of workflows, active webhooks, and other fundamental logic. |
packages/editor-ui | The Vue 3 frontend application that provides the visual workflow editor. |
packages/workflow | Defines the core interfaces and types for workflows, used by both the frontend and backend. |
packages/@n8n/api-types | A dedicated package for shared TypeScript interfaces, ensuring type safety and consistency between the frontend and backend. |
packages/nodes-base | Contains the built-in integration nodes that form the building blocks of n8n workflows. |
@n8n/design-system | A Vue component library that ensures a consistent look and feel across the UI. |
@n8n/create-node | A scaffolding tool for creating new custom community nodes. |
Sources: AGENTS.md:45-56, CONTRIBUTING.md:20-33, packages/@n8n/create-node/README.md:3
Technology Stack
n8n leverages a modern technology stack for its frontend, backend, and testing infrastructure.
| Category | Technology | Description |
|---|---|---|
| Backend | Node.js, TypeScript, Express | The server-side is built on Node.js with Express for the REST API, all written in TypeScript. |
| Frontend | Vue 3, TypeScript, Vite, Pinia | The user interface is a single-page application built with Vue 3, using Pinia for state management and Vite for the build tool. |
| Database | TypeORM | The data access layer uses TypeORM, providing support for SQLite, PostgreSQL, and MySQL. |
| Testing | Jest, Playwright, Vitest | Unit testing is done with Jest (backend) and Vitest (frontend), while end-to-end testing is handled by Playwright. |
| Code Quality | Biome, ESLint, lefthook | Code formatting is managed by Biome, linting by ESLint, and pre-commit checks are enforced with lefthook git hooks. |
Sources: AGENTS.md:58-63
Development and Testing
The development workflow is designed for efficiency, with support for hot reloading and selective package development to conserve system resources.
Development Cycle
The typical development cycle involves starting the application in development mode, making changes, and then running tests before committing.
This flowchart shows the standard development workflow for n8n.
Sources: CONTRIBUTING.md:100-113
Hot reloading for nodes can be enabled with the N8N_DEV_RELOAD=true environment variable, which avoids the need for a full server restart when developing nodes.
Sources: CONTRIBUTING.md:115-118
Testing Architecture
n8n employs a multi-layered testing strategy to ensure code quality and reliability.
Unit Testing
Unit tests are written using Jest for the backend and Vitest for the frontend. The core principle is to mock all external dependencies, including API calls (using nock) and core n8n interfaces (using jest-mock-extended).
Sources: AGENTS.md:120-123, packages/nodes-base/TESTING_PROMPT.md:13-16
End-to-End (E2E) Testing
E2E tests are built with Playwright and follow a structured, multi-layer architecture to promote separation of concerns and reusability.
The UI testing architecture consists of four layers:
This diagram illustrates the four-layer architecture for UI testing with Playwright.
Sources: packages/testing/playwright/CONTRIBUTING.md:31-37
- Tests (
.spec.ts): Contain readable, high-level scenarios that describe business logic. - Composables (
*Composer.ts): Orchestrate complex, multi-page business workflows (e.g., executing a workflow and waiting for a notification). - Page Objects (
*Page.ts): Encapsulate UI interactions and element locators for a specific page. - BasePage: Provides common, reusable utility methods like
clickByTestId.
API-driven tests use a simpler two-layer approach, where test files directly use API service helpers to interact with the backend.
Sources: packages/testing/playwright/CONTRIBUTING.md:28-44, packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:73-82
Node Architecture
Nodes are the fundamental building blocks of n8n workflows. Each node is an implementation of the INodeType interface.
Sources: packages/nodes-base/AGENTS.md:5-9
Node Types
There are several types of nodes, categorized by their execution model:
- Programmatic Nodes: Implement custom logic within an
execute()method. - Declarative Nodes: Configure behavior using
requestDefaultsand routing definitions, often without a customexecute()method. - Trigger Nodes: Initiate workflow executions. They can be further divided into:
- Webhook Triggers: Implement
webhook()andwebhookMethodsfor handling HTTP requests. - Polling Triggers: Set
polling: truein their description and implement apoll()method to periodically check for new data. - Generic Triggers: Implement a
trigger()function for other event-based mechanisms like MQTT.
- Webhook Triggers: Implement
Sources: packages/nodes-base/AGENTS.md:11-23
Node Project Structure
A typical node project, generated by @n8n/create-node, has a standardized structure:
my-awesome-api-node/
├── src/
│ ├── nodes/
│ │ └── MyAwesomeApi/
│ │ ├── MyAwesomeApi.node.ts # Main node logic
│ │ └── MyAwesomeApi.node.json # Node metadata
│ └── credentials/
│ └── MyAwesomeApiAuth.credentials.ts
├── package.json
└── tsconfig.json
This shows the standard file structure for a custom n8n node.
Sources: packages/@n8n/create-node/README.md:145-155
AI Workflow Builder
The AI Workflow Builder is an advanced feature that uses an AI agent to construct workflows from natural language prompts. This system follows a structured, multi-phase process to ensure the creation of robust and correct workflows.
AI Workflow Creation Sequence
The AI agent follows a mandatory sequence of phases to build a workflow. This process emphasizes parallel execution for efficiency.
This flowchart outlines the sequential and parallel phases the AI agent follows to construct a workflow.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:16-101
Best Practices and Techniques
The AI agent leverages a knowledge base of best practices for various workflow techniques to inform its decisions. These documents provide guidance on node selection, configuration, and common pitfalls.
| Workflow Technique | Key Best Practices | Recommended Nodes |
|---|---|---|
| Data Analysis | Use Split In Batches for large datasets. Pin data during development. Structure as Input → Transform → Output. | n8n-nodes-base.httpRequest, n8n-nodes-base.set, n8n-nodes-base.filter, n8n-nodes-base.code |
| Triage | Use Switch for multi-way branching. Always include a default path. Classify via rules (IF/Switch) or AI. | n8n-nodes-base.webhook, n8n-nodes-base.switch, @n8n/n8n-nodes-langchain.agent |
| Knowledge Base | Split into separate Ingestion and Query workflows. Use consistent embedding models. Limit retrieved documents to 3-5. | @n8n/n8n-nodes-langchain.documentDefaultDataLoader, @n8n/n8n-nodes-langchain.textSplitterRecursiveCharacterTextSplitter, @n8n/n8n-nodes-langchain.vectorStorePinecone, @n8n/n8n-nodes-langchain.agent |
| Data Transformation | Filter data early. Use Set with "Keep Only Set" carefully. Use Code node for complex logic. | n8n-nodes-base.set, n8n-nodes-base.merge, n8n-nodes-base.code, n8n-nodes-base.splitInBatches |
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/knowledge-base.ts, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-transformation.ts
Conclusion
The high-level architecture of n8n is centered around a modular monorepo that enables robust, scalable, and maintainable development. Its clear separation of concerns between the core engine, UI, and nodes, combined with a modern technology stack, provides a powerful foundation for workflow automation. The structured development and testing workflows, particularly the layered E2E testing approach, ensure high quality. Advanced features like the AI Workflow Builder further demonstrate the sophistication of the architecture, employing a phased, best-practice-driven process to translate user intent into functional workflows.
Sources: AGENTS.md, CONTRIBUTING.md, packages/testing/playwright/CONTRIBUTING.md, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts