Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:n8n is a workflow automation platform built with a monorepo architecture managed by pnpm workspaces. The system is primarily written in TypeScript and consists of a Node.js backend, a Vue.js frontend, and an extensible node-based workflow engine. This structure allows for clear separation of concerns between different modules, such as the core execution engine, the command-line interface (CLI), the user interface (UI), and the various integration nodes.
The architecture emphasizes modularity and reusability. Key patterns include dependency injection, a controller-service-repository pattern in the backend, and a component-based structure in the frontend using a dedicated design system. The project is designed to be extensible, allowing for the creation of custom nodes and integrations.
Sources: CLAUDE.md:5-8, CONTRIBUTING.md:18-29
Monorepo and Package Structure
The n8n project is organized as a monorepo using pnpm workspaces, with Turbo for build orchestration. This setup facilitates module management and automatically links local package dependencies.
Sources: CLAUDE.md:38, CONTRIBUTING.md:43-46
The diagram below illustrates the high-level relationship between the key packages in the monorepo.
This diagram shows the separation between Frontend, Backend, and Shared packages, with arrows indicating key dependencies.
Sources: CLAUDE.md:41-55
Key Packages
The monorepo contains several important packages, each with a specific responsibility:
| Package | Description |
|---|---|
packages/@n8n/api-types | Contains shared TypeScript interfaces used by both the frontend and backend to ensure type safety across the stack. |
packages/workflow | Defines the core interfaces and types for workflows, used by both frontend and backend. |
packages/core | The core workflow execution engine. It handles the logic for running workflows, managing active webhooks, and processing nodes. |
packages/cli | Implements the Express.js server, the REST API endpoints, and command-line interface (CLI) commands. |
packages/editor-ui | The main frontend application, built with Vue 3. It provides the workflow editor interface for users. |
packages/@n8n/design-system | A Vue component library that ensures UI consistency across the application. |
packages/nodes-base | Contains the built-in nodes for various services and integrations. |
packages/@n8n/nodes-langchain | A specialized package for AI and LangChain-related nodes. |
packages/@n8n/config | Provides centralized configuration management for the application. |
Sources: CLAUDE.md:41-55, CONTRIBUTING.md:21-29
Technology Stack
The project utilizes a modern technology stack for its frontend, backend, and testing infrastructure.
| Category | Technologies |
|---|---|
| Frontend | Vue 3, TypeScript, Vite, Pinia, Storybook |
| Backend | Node.js, TypeScript, Express, TypeORM |
| Database | SQLite, PostgreSQL, MySQL (via TypeORM) |
| Testing | Jest (Unit), Playwright (E2E), Vitest (Frontend Unit) |
| Code Quality | Biome (Formatting), ESLint, lefthook (Git Hooks) |
Sources: CLAUDE.md:57-62, CLAUDE.md:100-104
Backend Architecture
The backend is built on Node.js and Express, and it follows a layered architecture pattern.
Sources: CLAUDE.md:59, CLAUDE.md:65
Key Architectural Patterns
- Controller-Service-Repository: The backend is structured similarly to an MVC pattern, separating concerns into controllers for handling API requests, services for business logic, and repositories for data access.
- Dependency Injection: The system uses a custom Inversion of Control (IoC) container via the
@n8n/dipackage to manage dependencies. - Event-Driven: An internal event bus is used for decoupled communication between different parts of the system.
Sources: CLAUDE.md:64-67
API Layer
The packages/cli package exposes a REST API. API endpoints are defined in controllers, which handle incoming HTTP requests, validate inputs, and delegate business logic to services. API testing is a key part of the development process, with integration tests verifying endpoint behavior and access control based on scopes.
The following sequence diagram shows a typical flow for a public API request with scope-based authorization enabled.
This diagram illustrates how an API request is processed through authentication, controller, service, and repository layers.
Sources: packages/cli/test/integration/public-api/endpoints-with-scopes-enabled.test.ts:248-285
Frontend Architecture
The frontend is a single-page application (SPA) built with Vue 3 and TypeScript. It is served by Vite in development.
Sources: CLAUDE.md:58
Key Components
packages/editor-ui: The main application package containing the workflow editor, components, and business logic.@n8n/design-system: A separate package for reusable Vue components, ensuring a consistent look and feel.- Pinia: Used for state management, providing centralized stores for UI state, user data, and more.
- Vue Router: Manages navigation and views within the application.
Sources: CLAUDE.md:43-55
The constants.ts file defines a large number of constants used throughout the UI, including modal keys, node types, and API-related values, which helps maintain consistency and avoid magic strings.
Sources: packages/frontend/editor-ui/src/constants.ts
Testing Architecture
The project has a comprehensive testing strategy that includes unit, integration, and end-to-end (E2E) tests. The E2E testing framework, built on Playwright, is particularly well-structured.
Sources: CLAUDE.md:92-104, packages/testing/playwright/CONTRIBUTING.md:23-35
UI Testing (Playwright)
UI testing follows a four-layer architecture to promote separation of concerns and create readable, maintainable tests.
This diagram shows the layered approach to UI testing, from high-level test specifications down to low-level page interactions.
Sources: packages/testing/playwright/CONTRIBUTING.md:25-30
API Testing (Playwright)
API testing uses a simpler, two-layer approach.
This diagram shows that API tests directly use service helpers to interact with the backend API.
Sources: packages/testing/playwright/CONTRIBUTING.md:32-35
Test Configuration and Execution
- Unit Tests: Run with
pnpm testusing Jest. - E2E Tests: The old Cypress tests are being migrated to Playwright. New E2E tests are written using Playwright.
- Workflow Tests: A dedicated framework exists for testing CLI-based workflow execution, which can perform schema validation on node outputs to detect breaking changes in external APIs.
Sources: CLAUDE.md:92-104, packages/testing/playwright/tests/cli-workflows/README.md:29-32, cypress/e2e/group5/29-templates.cy.ts
AI Workflow Builder Evaluations
A dedicated evaluation framework exists to test the AI Workflow Builder's ability to generate correct n8n workflows from natural language prompts. This system has a parallel architecture to run evaluations for both CLI and Langsmith environments.
The evaluation covers multiple metrics, each with a specialized evaluator chain:
- Functionality
- Connections
- Expressions
- Node Configuration
- Efficiency
- Data Flow
- Maintainability
Each metric is scored, and violations are categorized by severity (Critical, Major, Minor) to provide a comprehensive assessment of the generated workflow's quality.
Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md:5-10, packages/@n8n/ai-workflow-builder.ee/evaluations/chains/evaluators/maintainability-evaluator.ts:5-16
Summary
The n8n architecture is a well-defined, modular system that leverages a modern TypeScript-based stack. Its monorepo structure with pnpm workspaces provides a solid foundation for developing and maintaining the various parts of the platform, from the backend API and workflow engine to the Vue.js frontend. The clear separation of concerns is evident not only in the package structure but also in the design patterns used within the backend, frontend, and the sophisticated, multi-layered testing framework. This design facilitates extensibility, maintainability, and robust testing.
Sources: CLAUDE.md, CONTRIBUTING.md