High-level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
n8n is a node-based workflow automation platform that enables users to connect different services and automate data flows. The system follows a monorepo structure, using TypeScript for both its Node.js backend and Vue.js frontend. The architecture emphasizes extensibility through a modular node system and a core execution engine that manages workflow traversal and item-based processing.
Sources: AGENTS.md:3-8, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:5-9
Monorepo Structure
The project uses pnpm workspaces and Turbo for build orchestration. It separates concerns into distinct packages for the engine, the web interface, shared types, and various integrations.
Key Packages
| Package | Description |
|---|---|
packages/workflow | Defines core workflow interfaces and types. |
packages/core | Contains the workflow execution engine. |
packages/cli | Implements the Express server, REST API, and CLI commands. |
packages/frontend/editor-ui | The Vue 3 application for the workflow editor. |
packages/nodes-base | A collection of built-in nodes for common integrations. |
packages/@n8n/api-types | Shared TypeScript interfaces for frontend/backend communication. |
Sources: AGENTS.md:120-140, CONTRIBUTING.md:43-52
Dependency and Build Flow
The diagram below illustrates the relationship between the major architectural modules.
Sources: AGENTS.md:120-140, CONTRIBUTING.md:43-52
Core Architectural Patterns
n8n implements several design patterns to maintain separation between business logic, persistence, and the execution environment.
1. Persistence Layer and TypeORM Boundary
The system enforces a strict boundary for the persistence layer. Business logic (services and controllers) must not import directly from @n8n/typeorm. Instead, it uses use-case-named repository methods that return domain-shaped values. Transaction orchestration is handled via an abstract TransactionRunner to keep driver-specific logic hidden.
Sources: AGENTS.md:200-218
2. Event-Driven Communication
An internal event bus facilitates decoupled communication between different system modules. This allows for telemetry tracking and system-wide reactions to workflow events without hard-coding dependencies between modules.
Sources: AGENTS.md:150-155
3. Dependency Injection (DI)
The backend uses @n8n/di for its Inversion of Control (IoC) container. This manages the lifecycle of services and ensures that dependencies are resolved consistently across the application.
Sources: AGENTS.md:150-152
Node Integration System
Nodes are the fundamental building blocks of n8n workflows. Each node is a specialized module that implements a standard interface to interact with the execution engine.
Node Categories
Nodes are classified by their execution style and function:
- Trigger Nodes: Start workflows based on events (Webhooks), time (Polling), or manual activation.
- Programmatic Nodes: Implement custom logic through an
execute()function. - Declarative Nodes: Use routing configurations and
requestDefaultsto define API interactions without writing imperative code.
Sources: packages/nodes-base/AGENTS.md:7-30
Execution Logic
The execution engine processes each node once per input item. If a node outputs multiple items, downstream nodes execute once for each item received.
Testing Infrastructure
n8n employs a multi-layered testing strategy to ensure reliability across the monorepo.
- Unit Tests: Handled by Vitest, testing individual functions and classes within packages.
- Integration/Workflow Tests: Use
NodeTestHarnesswith JSON-based workflow definitions to verify node behavior in a controlled environment. - E2E Tests: Orchestrated by Playwright, these tests cover the full stack by simulating user interactions in the Vue frontend and verifying effects in the backend.
Playwright E2E Architecture
The E2E suite uses a four-layer approach for UI testing:
- Tests (.spec.ts): Scenario-based descriptions.
- Composables: Complex business workflows (e.g.,
WorkflowComposer). - Page Objects: Locators and simple UI actions.
- BasePage: Common utility methods.
Sources: packages/quality/testing/playwright/CONTRIBUTING.md:40-60, packages/nodes-base/AGENTS.md:58-65
Summary
n8n's architecture is a modular, monorepo-based system that centers on a decoupled execution engine and a versatile node-based integration layer. By enforcing strict boundaries between persistence, business logic, and the UI, the project maintains high extensibility. This structure supports a diverse ecosystem of community and core nodes while providing robust testing and deployment capabilities.