Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The n8n project is built using a monorepo structure to manage its diverse set of modules, including the Node.js backend, Vue.js frontend, and various internal packages. This architecture facilitates code sharing, consistent dependency management, and unified build orchestration across the entire ecosystem.
Sources: AGENTS.md:5-7, CONTRIBUTING.md:16-17
Core Workspace Structure
The project uses pnpm workspaces to manage multiple packages within a single repository. This setup automatically handles file-linking between modules that depend on each other, ensuring that local changes in a shared package are immediately reflected in dependent modules.
Sources: CONTRIBUTING.md:46-49, AGENTS.md:104-105
Workspace Dependency Flow
The following diagram illustrates how core packages within the monorepo interact and depend on one another.
Note: This diagram shows the high-level dependency flow where core logic and types are shared across the CLI and Frontend.
Sources: AGENTS.md:109-120, CONTRIBUTING.md:20-30
Primary Packages
| Package Path | Description | Key Responsibility |
|---|---|---|
packages/@n8n/api-types | Shared TS interfaces | Communication contract between Frontend and Backend |
packages/workflow | Core interfaces and types | Defines the structure of workflows, nodes, and connections |
packages/core | Execution engine | Handles the logic for running active workflows and webhooks |
packages/cli | Server and REST API | Entry point for the application; contains Express server logic |
packages/frontend/editor-ui | Vue 3 Application | The visual workflow editor interface |
packages/nodes-base | Integration Nodes | Collection of built-in nodes (e.g., HTTP Request, Gmail) |
Sources: AGENTS.md:112-120, CONTRIBUTING.md:20-30
Build and Orchestration
n8n utilizes Turbo (Turborepo) for build orchestration. This allows for efficient, cached builds and the ability to run tasks across multiple packages in parallel while respecting the dependency graph.
Sources: AGENTS.md:104-105, AGENTS.md:46-48
Development Lifecycles
The monorepo supports selective development modes to manage system resources, as running the entire stack can be intensive.
pnpm dev:be: Focuses solely on backend development (CLI and Core).pnpm dev:fe: Runs only the frontend development server and design system.pnpm dev:ai: Specialized mode for AI/LangChain node development.
Sources: CONTRIBUTING.md:139-150, AGENTS.md:126-128
Testing Architecture
The monorepo enforces a layered testing strategy to ensure stability across different packages. This includes unit tests, integration tests, and End-to-End (E2E) tests.
Layered E2E Testing Model
E2E tests, managed via Playwright, follow a strict four-layer approach to maintain isolation and readability.
Note: This architecture ensures that selectors are encapsulated within Page Objects, while business logic resides in Composables.
Sources: packages/testing/playwright/CONTRIBUTING.md:38-48, packages/testing/janitor/README.md:17-45
Architecture Enforcement (Janitor)
A specialized tool called Janitor is used to perform static analysis on the monorepo to prevent architecture drift. It enforces rules such as:
- Selector Purity: Raw Playwright locators cannot appear in tests or flows.
- Boundary Protection: Pages cannot import other pages directly to prevent coupling.
- Dead Code Detection: Identifies unused public methods in page objects across the monorepo.
Sources: packages/testing/janitor/README.md:120-175, packages/testing/playwright/AGENTS.md:32-55
Key Architectural Patterns
- Dependency Injection: The project uses
@n8n/difor its Inversion of Control (IoC) container to manage service lifecycles. - Controller-Service-Repository: The backend follows an MVC-inspired pattern for structured API development.
- Event-Driven: An internal event bus is used for decoupled communication between different backend modules.
- Versioned Node Types: Nodes support "Full versioning" through the
VersionedNodeTypeclass, allowing multiple versions of a single node (e.g.,Set.node.ts) to coexist.
Sources: AGENTS.md:129-135, packages/nodes-base/AGENTS.md:37-38
Summary
The n8n monorepo architecture is designed for scalability and maintainability. By leveraging pnpm workspaces and Turbo, it manages a complex ecosystem of TypeScript packages. The architecture emphasizes strict layer separation, shared core types via @n8n/api-types and n8n-workflow, and automated architectural enforcement to ensure that as the project grows, it remains robust and easy to navigate for developers.