Monorepo Architecture & Packages
Relevant source files
The following files were used as context for generating this wiki page:
n8n uses a monorepo structure managed by pnpm workspaces to organize its workflow automation platform. This architecture separates the Node.js backend, the Vue.js frontend, and the extensible node-based workflow engine into distinct, interoperable packages. Turbo handles build orchestration across these modules to ensure efficient development and deployment.
Sources: AGENTS.md:7-10, CONTRIBUTING.md:41-42
Core Package Structure
The repository organizes code into functional modules under the packages/ directory. Each package maintains its own build configuration while sharing centralized governance for linting, encryption, and database access.
Primary Packages
| Package Path | Description |
|---|---|
packages/workflow | Defines core workflow interfaces and types used by both frontend and backend. |
packages/core | Contains the workflow execution engine, handles active webhooks and workflow logic. |
packages/cli | Houses the Express server, REST API, and CLI commands to run the application. |
packages/frontend/editor-ui | The main Vue 3 frontend application for the workflow editor. |
packages/nodes-base | Contains the built-in nodes for various service integrations. |
packages/@n8n/design-system | Centralized Vue component library and design tokens. |
packages/@n8n/api-types | Shared TypeScript interfaces for frontend and backend communication. |
Sources: AGENTS.md:143-156, CONTRIBUTING.md:44-53
Dependency and Build Flow
The monorepo uses pnpm workspaces to link modules. When one package depends on another within the repository, pnpm creates file-system links to facilitate development without external registry publishing.
This diagram shows the high-level dependency flow between major packages.
Sources: AGENTS.md:143-156, CONTRIBUTING.md:65-68
Architectural Layers
n8n enforces strict boundaries between logic layers to maintain code health and security.
Persistence and Database Layer
TypeORM logic resides within the persistence layer. Business logic, such as services and controllers, must not import directly from @n8n/typeorm. Instead, modules use the @n8n/db package and abstract repositories.
- Transaction Management: Developers use a
TransactionRunnerfrom@n8n/dbto wrap units of work. - Repositories: Custom methods in repositories return domain-shaped values rather than exposing TypeORM primitives.
Sources: AGENTS.md:214-230
Security and Encryption Boundary
Sensitive data encryption occurs only through cipher.encryptV2() and cipher.decryptV2().
- Logic Location: Raw AES classes are restricted to
packages/core/src/encryption/. - Policy Enforcement: CI rules prevent the deletion of deployment keys and reject inline ESLint disables for encryption-related code.
Sources: AGENTS.md:275-288
ESLint Configuration Layers
Rule policies are stratified into four shared configurations within @n8n/eslint-config.
| Layer | Subpath | Target Environment |
|---|---|---|
baseConfig | .../base | Runtime-agnostic libraries |
backendConfig | .../backend | Node.js packages (includes encryption boundaries) |
frontendConfig | .../frontend | Vue.js packages |
nodesConfig | .../nodes | nodes-base and LangChain nodes (includes node file rules) |
Sources: AGENTS.md:255-265
Specialized Package Groups
Quality Engineering and Testing
The packages/quality directory centralizes testing infrastructure, environment management, and efficiency benchmarking.
This hierarchy represents the organization of quality-related tools and configurations.
Sources: packages/quality/AGENTS.md:1-12
Frontend Design System
The @n8n/design-system package provides a Vue 3 component library. It includes design tokens, icons, and specialized directives like v-n8n-html. Components are generic and intended for reuse across all frontend modules.
- Consumption: Integrated into apps via
N8nPlugin. - Exports: Provides the barrel export for components, CSS for styles/themes, and SCSS sources for mixins.
Sources: packages/frontend/@n8n/design-system/README.md:13-25, 68-75
Development Infrastructure
Build and Setup Commands
The monorepo uses standardized pnpm scripts for lifecycle management:
pnpm agent:setup: Chains install, build, and full-suite testing for new environments.pnpm build: Compiles all packages using Turbo.pnpm dev:be/pnpm dev:fe: Starts filtered development servers for the backend or frontend respectively.
Sources: AGENTS.md:83-88, 114-125
Git Hooks and Code Health
The repository utilizes lefthook for git hooks and biome for formatting. CI runs @n8n/code-health static analysis to verify monorepo rules, including dependency hygiene and proper encryption boundary coverage.
Sources: AGENTS.md:159-160, 311-313
Summary
n8n's monorepo architecture enables a modular yet unified development experience. By segregating the execution engine (core), the user interface (editor-ui), and individual integrations (nodes-base), the project maintains clear responsibility boundaries. Strict enforcement of persistence and encryption layers ensures that security and data integrity are handled consistently across the growing ecosystem of packages.
Sources: AGENTS.md:141-156, CONTRIBUTING.md:41-55