Repository Structure

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CONTRIBUTING.md
• docker/images/n8n/README.md
• packages/@n8n/create-node/README.md
• packages/@n8n/node-cli/README.md
• packages/nodes-base/AGENTS.md
• packages/nodes-base/TESTING_PROMPT_WORKFLOW.md
• packages/testing/playwright/CONTRIBUTING.md
• packages/testing/playwright/tests/cli-workflows/README.md
• packages/nodes-base/nodes/Github/Github.node.json
• packages/nodes-base/nodes/Webhook/Webhook.node.json
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
• packages/cli/src/modules/breaking-changes/rules/v2/tests/git-node-bare-repos.rule.test.ts
• packages/frontend/editor-ui/src/app/components/WhatsNewModal.test.ts

The n8n project is a workflow automation platform built with TypeScript. It is structured as a monorepo managed by pnpm workspaces, comprising a Node.js backend, a Vue.js frontend, and an extensible node-based workflow engine. This structure facilitates modular development, code sharing, and streamlined build processes across its various components.

The repository is organized to support independent package development, a comprehensive testing strategy, and containerized deployment. Key architectural patterns include dependency injection, a controller-service-repository pattern for the backend, and an event-driven internal bus.

Sources: AGENTS.md:5-8, CONTRIBUTING.md:21-23, AGENTS.md:52-60

Monorepo Management

The n8n monorepo uses pnpm workspaces to manage its multiple packages. This allows for inter-package dependencies to be linked locally, simplifying development and ensuring consistency. The build process is orchestrated by Turborepo, which optimizes build times by caching outputs and running tasks in parallel.

Sources: AGENTS.md:49, CONTRIBUTING.md:43-46

The diagram below illustrates the monorepo management tools and their interaction with the packages.

Directory & Package Structure

The repository is divided into several key directories, with the most important being /packages, which contains all the individual n8n modules.

Sources: CONTRIBUTING.md:25-27

Key Packages

The monorepo contains numerous packages, each with a specific responsibility. The following table highlights the most critical ones:

Package	Description	Source File
packages/cli	Contains the Express server, REST API, and Command Line Interface (CLI) commands.	CONTRIBUTING.md:30
packages/core	The core workflow execution engine. Handles workflow execution, active webhooks, and workflows.	CONTRIBUTING.md:31-34
packages/editor-ui	The Vue.js frontend application for the workflow editor.	CONTRIBUTING.md:36
packages/nodes-base	Contains all the built-in nodes for various integrations.	CONTRIBUTING.md:38
packages/workflow	Defines core workflow interfaces and types used by both frontend and backend.	CONTRIBUTING.md:39-40
packages/@n8n/design-system	A Vue component library for UI consistency.	AGENTS.md:44
packages/@n8n/api-types	Contains shared TypeScript interfaces for communication between the frontend and backend.	AGENTS.md:36
packages/node-dev	A CLI tool to facilitate the creation of new n8n nodes.	CONTRIBUTING.md:37

High-Level Package Architecture

This diagram shows the high-level relationship between the main packages in the n8n monorepo.

Technology Stack

The project utilizes a modern technology stack for its frontend, backend, and development tooling.

Category	Technologies
Frontend	Vue 3, TypeScript, Vite, Pinia, Storybook
Backend	Node.js, TypeScript, Express, TypeORM
Database	SQLite (default), PostgreSQL, MySQL
Testing	Jest (Unit), Playwright (E2E), Vitest (Frontend Unit)
Code Quality	Biome (Formatter), ESLint, lefthook (Git hooks)

Sources: AGENTS.md:48-51, AGENTS.md:100-103

Development Workflow

The development cycle is streamlined with pnpm scripts that handle building, watching for changes, and running n8n in development mode.

Development Commands

• pnpm dev: Runs the full stack in development mode with hot-reloading for both frontend and backend.
• pnpm dev:be: Runs backend-only development, excluding frontend packages.
• pnpm dev:fe: Runs the backend server and the frontend development server.
• pnpm dev:ai: Runs a minimal set of packages for AI/LangChain node development.
• N8N_DEV_RELOAD=true pnpm dev: Enables hot reload for nodes and credentials without a full server restart.

Sources: CONTRIBUTING.md:106-146

Basic Development Cycle

The diagram below outlines the typical development workflow for a contributor.

Node Development

Custom nodes are a core part of the n8n ecosystem. The repository provides tools to scaffold, develop, and publish new nodes.

Node Scaffolding

New nodes can be created using the @n8n/create-node package.

npm create @n8n/node@latest

This command initiates an interactive setup process that generates a new node project with a predefined structure, including the main node logic file (.node.ts), metadata (.node.json), and credential files.

Sources: packages/@n8n/create-node/README.md:5-8, packages/@n8n/create-node/README.md:110-119

Node Project Structure

A generated node project has the following 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
└── README.md

Sources: packages/@n8n/create-node/README.md:110-119

The n8n-node CLI tool, provided by @n8n/node-cli, is used under the hood for development tasks like dev, build, lint, and release.

Sources: packages/@n8n/node-cli/README.md:7-24

Testing Strategy

n8n employs a multi-layered testing strategy to ensure code quality and stability, including unit tests, end-to-end (E2E) tests, and workflow-based tests.

Unit Testing

Unit tests are written with Jest for the backend and Vitest for the frontend. They are located alongside the source code in __tests__ directories or as .test.ts files. All external dependencies, such as APIs and databases, are mocked.

• Command: pnpm test <file_name>
• Mocking: jest-mock-extended for interfaces, nock for HTTP requests.

Sources: AGENTS.md:100-103, packages/nodes-base/TESTING_PROMPT.md:13-16, packages/cli/src/modules/breaking-changes/rules/v2/tests/git-node-bare-repos.rule.test.ts

End-to-End (E2E) Testing

E2E tests are implemented using Playwright. These tests interact with a running n8n instance to simulate user behavior and verify UI and backend integration.

• Run locally: pnpm --filter=n8n-playwright test:local
• Run in UI mode: pnpm --filter=n8n-playwright test:local --ui

Sources: CONTRIBUTING.md:213-218

The E2E testing framework follows a four-layer architecture to promote separation of concerns and reusability.

This diagram shows the UI testing architecture where tests use high-level composables, which in turn orchestrate actions on page objects.
Sources: packages/testing/playwright/CONTRIBUTING.md:31-37

Workflow Testing

Workflow tests validate the end-to-end execution of n8n workflows. There are two primary approaches:

1. NodeTestHarness: Used within packages/nodes-base, this approach uses .workflow.json files to define a workflow, mock API calls with nock, and assert the final output.
2. CLI-based Workflow Testing: A Playwright-based framework in packages/testing/playwright/tests/cli-workflows that executes workflows via the CLI and can perform schema validation on the output to detect breaking changes in APIs.

Sources: packages/nodes-base/TESTING_PROMPT_WORKFLOW.md:3-6, packages/testing/playwright/tests/cli-workflows/README.md:10-13

Deployment with Docker

n8n is designed to be deployed using Docker. The official Docker image is available at docker.n8n.io/n8nio/n8n.

A typical Docker run command involves:

• Mapping port 5678.
• Creating and mounting a volume (n8n_data) to /home/node/.n8n to persist workflow data, credentials, and the encryption key.

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

For production setups, using docker-compose with a PostgreSQL database is recommended over the default SQLite.

Sources: docker/images/n8n/README.md:52-60, docker/images/n8n/README.md:70-74