n8n Overview

Relevant source files

• CHANGELOG.md
• package.json
• packages/@n8n/agents/package.json
• packages/@n8n/api-types/package.json
• packages/@n8n/api-types/src/frontend-settings.ts
• packages/@n8n/backend-common/src/license-state.ts
• packages/@n8n/config/package.json
• packages/@n8n/config/src/index.ts
• packages/@n8n/config/test/config.test.ts
• packages/@n8n/constants/src/index.ts
• packages/@n8n/instance-ai/package.json
• packages/@n8n/nodes-langchain/package.json
• packages/@n8n/task-runner/package.json
• packages/cli/package.json
• packages/cli/src/__tests__/license.test.ts
• packages/cli/src/abstract-server.ts
• packages/cli/src/commands/base-command.ts
• packages/cli/src/commands/start.ts
• packages/cli/src/commands/webhook.ts
• packages/cli/src/commands/worker.ts
• packages/cli/src/config/schema.ts
• packages/cli/src/constants.ts
• packages/cli/src/controllers/e2e.controller.ts
• packages/cli/src/license.ts
• packages/cli/src/scaling/__tests__/worker-server.test.ts
• packages/cli/src/scaling/worker-server.ts
• packages/cli/src/server.ts
• packages/cli/src/services/__tests__/frontend.service.test.ts
• packages/cli/src/services/frontend.service.ts
• packages/cli/test/integration/commands/worker.cmd.test.ts
• packages/cli/test/integration/shared/license.ts
• packages/cli/test/integration/shared/types.ts
• packages/cli/test/integration/shared/utils/test-server.ts
• packages/core/package.json
• packages/frontend/@n8n/chat/package.json
• packages/frontend/@n8n/design-system/package.json
• packages/frontend/editor-ui/package.json
• packages/frontend/editor-ui/src/__tests__/defaults.ts
• packages/frontend/editor-ui/src/__tests__/mocks.ts
• packages/frontend/editor-ui/src/app/composables/useBackendStatus.spec.ts
• packages/frontend/editor-ui/src/app/composables/useBackendStatus.ts
• packages/frontend/editor-ui/src/app/constants/enterprise.ts
• packages/frontend/editor-ui/src/app/stores/settings.store.test.ts
• packages/frontend/editor-ui/src/app/stores/settings.store.ts
• packages/node-dev/package.json
• packages/nodes-base/package.json
• packages/workflow/package.json
• pnpm-lock.yaml
• pnpm-workspace.yaml

This document provides a high-level introduction to n8n's architecture, monorepo structure, and core packages. It explains how the codebase is organized into distinct packages with clear dependency boundaries and how the system operates in different runtime modes.

For detailed information about specific subsystems, see:

• Monorepo organization: Monorepo Structure and Core Packages
• Execution modes and scaling: Runtime Architecture and Process Models
• Build pipeline and dependencies: Package Dependencies and Build System

---

What is n8n

n8n is a workflow automation platform that allows users to create, execute, and monitor workflows composed of interconnected nodes. Each node represents an integration with an external service or a data transformation operation. The platform consists of:

• Workflow Canvas: A Vue 3-based visual editor where users design workflows by connecting nodes.
• Execution Engine: A Node.js backend that runs workflows locally or distributed via queue workers.
• Node Ecosystem: 500+ built-in integrations plus support for custom community nodes.
• AI Features: LangChain integration, Chat Hub for conversational workflows, and the new Instance AI autonomous agent system.

The system is built as a TypeScript monorepo using pnpm workspaces, with clear separation between frontend, backend, and shared packages.

Sources: packages/cli/package.json2-4 package.json2-3 CHANGELOG.md1-21

---

Monorepo Structure

n8n is organized as a pnpm workspace with packages grouped by function. The monorepo uses Turbo for build orchestration and dependency graph management.

Package Organization

Sources: pnpm-workspace.yaml1-6 package.json1-53

Key Package Roles

Package	Path	Purpose	Entry Point
n8n-workflow	packages/workflow/	Core workflow abstractions, types, and expression engine	packages/workflow/package.json5-12
n8n-core	packages/core/	Workflow execution engine, node loading, credentials	packages/core/package.json5-6
n8n (CLI)	packages/cli/	Main application server, REST API, database, webhooks	packages/cli/package.json5-6
n8n-nodes-base	packages/nodes-base/	500+ built-in node integrations	packages/nodes-base/package.json5
@n8n/n8n-nodes-langchain	packages/@n8n/nodes-langchain/	AI/LLM nodes using LangChain	packages/@n8n/nodes-langchain/package.json5-18
n8n-editor-ui	packages/frontend/editor-ui/	Vue 3 workflow canvas and UI	packages/frontend/editor-ui/package.json2-6
@n8n/config	packages/@n8n/config/	Configuration schema and validation via GlobalConfig	packages/@n8n/config/package.json5-6
@n8n/di	packages/@n8n/di/	Dependency injection framework	packages/cli/package.json127
@n8n/instance-ai	packages/@n8n/instance-ai/	Deep agent orchestrator and autonomous tools	packages/cli/package.json130
@n8n/task-runner	packages/@n8n/task-runner/	Sandboxed JavaScript/Python execution	packages/cli/package.json135

Sources: pnpm-workspace.yaml1-6 packages/cli/package.json115-146 packages/workflow/package.json1-75

---

Architectural Layers

n8n follows a layered architecture with clear separation of concerns. The system can be conceptually divided into these layers:

System Architecture Diagram

Sources: packages/cli/package.json115-146 packages/core/package.json54-94 packages/cli/src/server.ts

---

Package Dependency Graph

The following diagram shows the dependency relationships between core packages, illustrating the unidirectional dependency flow:

Key Principles:

• No circular dependencies: The graph is acyclic, enabling clean builds and tree-shaking.
• Foundation independence: n8n-workflow, @n8n/config, and @n8n/di have minimal dependencies.
• Application layer: n8n CLI, n8n-nodes-base, and n8n-editor-ui are the primary executable artifacts.

Sources: packages/cli/package.json115-146 packages/workflow/package.json60-80 packages/core/package.json54-94

---

Runtime Modes and Process Architecture

n8n can run in multiple modes depending on the deployment configuration. Each mode starts from the same n8n CLI entrypoint but executes different server logic.

Process Modes

Sources: packages/cli/package.json45-47 package.json57-58 packages/cli/src/commands/start.ts57-63

Mode Descriptions

Mode	Command	Purpose	Key Classes
Main	n8n start	Full server with UI, API, webhooks, and local execution	Server, ActiveWorkflowManager
Worker	n8n worker	Queue-based job processor for distributed execution	WorkerServer, ScalingService
Webhook	n8n webhook	Dedicated webhook receiver (no UI/API)	WebhookServer

Execution Modes:

• Regular Mode: Workflows execute locally in the main process.
• Queue Mode: Workflows enqueued to Bull/Redis, processed by worker processes. Enabled by executions.mode = 'queue'.

Sources: packages/cli/package.json57-58 packages/cli/src/commands/start.ts109-112 packages/@n8n/config/test/config.test.ts44-209

---

Build System

The monorepo uses Turbo for incremental builds and pnpm for package management.

Build Configuration:

• Turbo: Orchestrates builds with dependency awareness and caching package.json13-22
• TypeScript: Packages compile via tsc using workspace configurations packages/cli/package.json10
• Path Aliases: tsc-alias resolves TypeScript path mappings after compilation packages/core/package.json16
• Vite: Used for frontend builds and modern ESM package exports packages/workflow/package.json25

Sources: package.json10-52 packages/cli/package.json7-12 packages/workflow/package.json21-35

---

Next Steps

For deeper dives into specific subsystems, refer to the child pages:

• Monorepo Structure and Core Packages: Detailed package descriptions and dependency analysis.
• Runtime Architecture and Process Models: Server initialization, process communication, and mode switching.
• Package Dependencies and Build System: Turbo pipeline and build orchestration details.