3. Technical Architecture: TypeScript Monorepo Done Right

3.1 Tech Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| Language | TypeScript 5.x (full stack) | Type safety everywhere |
| Backend runtime | Node.js 22+ | Async I/O, perfect for orchestration |
| Web framework | Express 5.1 | Mature middleware ecosystem |
| ORM | TypeORM | SQLite, PostgreSQL, MariaDB, MySQL |
| Task queue | Bull 4.16 (Redis) | Scheduled tasks, retries, priorities |
| Frontend | Vue 3 + Vite + Pinia | Composition API, reactive state |
| Canvas | Vue Flow 1.45 | Professional flowchart library |
| Code editor | CodeMirror 6 | JavaScript/Python code nodes |
| AI integration | @n8n/nodes-langchain | Native LangChain + LLM agents |
| Sandbox | isolated-vm | JavaScript code execution isolation |
| License | Sustainable Use License (fair-code) | Internal use free, commercial hosting paid |

3.2 Monorepo Layered Architecture

n8n follows a strict bottom-up, unidirectional dependency design. The core engine can run completely independently of the web server:

packages/workflow       ← Abstract: types, graph traversal, expression engine
        ↑
packages/core           ← Execution engine: WorkflowExecute, triggers, binary data
        ↑
packages/@n8n/config    ← Centralized configuration (class-validator)
packages/@n8n/db        ← TypeORM entities / repositories
packages/@n8n/di        ← IOC container (self-built @Service decorator)
        ↑
packages/cli            ← Express Server, REST API, scaling, entry point
        ↑
packages/nodes-base     ← 400+ built-in integration nodes
packages/@n8n/nodes-langchain  ← AI / LangChain nodes
packages/@n8n/task-runner      ← JS/Python code sandbox
        ↑
packages/editor-ui      ← Vue 3 visual editor

Direction rules: workflow does not depend on core, core does not depend on cli. This design allows the execution engine to run in worker processes without any UI dependencies.

3.3 Workflow Execution Engine

A workflow in n8n is a JSON configuration describing a DAG (Directed Acyclic Graph) of nodes. The execution flow:

1. Trigger (Webhook / Schedule / Polling / Queue) generates an execution
2. WorkflowRunner creates an Execution record and selects the mode (main process or queue)
3. WorkflowExecute performs topological sort on the nodes, building an execution stack
4. Each node's execute() method is called sequentially, returning INodeExecutionData[][] (2D array supports multiple outputs/branches)
5. Data flows between nodes via the expression engine (custom-built, supports {{ $json.field }} syntax)
6. Results are pushed to the editor UI via WebSocket/SSE

Two execution modes:

• Regular mode (default): Editor and execution engine in the same process. Simple, good for small-scale use.
• Queue mode: Main process handles triggers and pushes to Redis. Worker processes pull and execute. Required for production scale.

3.4 Credential Encryption

Credentials (API keys, OAuth tokens) are encrypted with AES-256 before storage. The encryption key is controlled by the N8N_ENCRYPTION_KEY environment variable, auto-generated on first launch.

Critical: In Queue mode, the main instance and ALL workers must share the same encryption key. If they don't match, workers will silently fail to decrypt credentials.

3.5 Webhook Processing

Webhook nodes expose n8n as a first-class HTTP service. When the main instance receives an external request:
1. It generates an execution ID
2. Pushes it to the Redis queue
3. An idle worker picks it up and processes it
4. The response is returned to the webhook caller

For high-throughput scenarios, use "respond immediately" to let the workflow complete asynchronously.

4. AI and LLM Integration: The Killer Feature

This is n8n's most significant advantage in 2026. The @n8n/nodes-langchain package provides deep LangChain integration, turning n8n into a visual AI agent orchestrator.

4.1 Model Flexibility (No Lock-in)

n8n supports connecting to:

• OpenAI: GPT-5.6, GPT-4.1, o-series models
• Anthropic: Claude Opus 4.8, Claude Sonnet
• Google: Gemini 3.5 Flash, Gemini 3.1 Pro
• Local: Ollama, LM Studio, any OpenAI-compatible endpoint
• Open-source: HuggingFace, Together AI, Groq

4.2 AI Component Architecture

n8n's AI capabilities are built around several core concepts:

Chains: Connect LLM, Prompt, and Tools into a linear pipeline. A chain is a sequence of operations that process input through an LLM.

Agents: The most powerful feature. ReAct Agents and Conversational Agents let the LLM autonomously decide which tools to call. The agent:
1. Receives a user query
2. Decides which available tool(s) to use
3. Calls the tool(s), receives results
4. Synthesizes the final response

Memory: Buffer Memory, Window Memory, and other patterns for maintaining conversation context across turns.

Tools: Any n8n node can become a tool for an agent. HTTP requests, database queries, custom code, Slack messages — the agent decides when to use them.

Vector Stores: Pinecone, Qdrant, Supabase, InMemory, and more. Used for RAG (Retrieval-Augmented Generation) pipelines.

RAG Pipeline Example:

[Schedule (daily)] → [HTTP (fetch data)] → [Code (clean/transform)]

  → [Embeddings (vectorize)] → [Vector Store (ingest)]

  → [AI Agent (Q&A)] → [Webhook (return result)]

4.3 Code Nodes

For operations that visual nodes can't handle, Code nodes provide escape hatches:

• JavaScript: Runs in isolated-vm — a V8 sandbox with resource limits. Can import npm packages.
• Python: Runs in a subprocess sandbox via @n8n/task-runner-python.

5. Deployment: From Zero to Production

5.1 Quick Start (npx)

npx n8n
→ http://localhost:5678

Great for evaluation, not for production.

5.2 Docker Single Container (SQLite)

docker volume create n8n_data

docker run -it --rm \

  --name n8n \

  -p 5678:5678 \

  -e GENERIC_TIMEZONE="UTC" \

  -e N8N_ENCRYPTION_KEY=$(openssl rand -hex 32) \

  -v n8n_data:/home/node/.n8n \

  docker.n8n.io/n8nio/n8n

5.3 Production Docker Compose (PostgreSQL + Traefik)

version: "3.8"

services:

  traefik:

    image: "traefik"

    restart: always

    command:

      - "--providers.docker=true"

      - "--providers.docker.exposedbydefault=false"

      - "--entrypoints.websecure.address=:443"

      - "--certificatesresolvers.mytlschallenge.acme.tlschallenge=true"

      - "--certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL}"

      - "--certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json"

    ports:

      - "80:80"

      - "443:443"

    volumes:

      - traefik_data:/letsencrypt

      - /var/run/docker.sock:/var/run/docker.sock:ro

postgres:

    image: postgres:16-alpine

    restart: always

    environment:

      POSTGRES_DB: n8n

      POSTGRES_USER: ${POSTGRES_USER}

      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    volumes:

      - pg_data:/var/lib/postgresql/data

n8n:

    image: docker.n8n.io/n8nio/n8n

    restart: always

    labels:

      - traefik.enable=true

      - traefik.http.routers.n8n.rule=Host(${SUBDOMAIN}.${DOMAIN_NAME})

      - traefik.http.routers.n8n.tls=true

      - traefik.http.routers.n8n.tls.certresolver=mytlschallenge

    environment:

      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}

      - N8N_PORT=5678

      - N8N_PROTOCOL=https

      - NODE_ENV=production

      - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/

      - DB_TYPE=postgresdb

      - DB_POSTGRESDB_HOST=postgres

      - DB_POSTGRESDB_DATABASE=n8n

      - DB_POSTGRESDB_USER=${POSTGRES_USER}

      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}

      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}

    depends_on:

      - postgres

    volumes:

      - n8n_data:/home/node/.n8n

volumes:

  n8n_data:

  traefik_data:

  pg_data:

# .env
DOMAIN_NAME=example.com
SUBDOMAIN=n8n
[email protected]
POSTGRES_USER=n8n
POSTGRES_PASSWORD=change_me
N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)

5.4 Queue Mode: Horizontal Scaling

When a single instance isn't enough, Queue mode is the path to production scale:

[Triggers/Webhooks] → [Main Instance] → [Redis Queue] → [Worker 1..N] → [PostgreSQL]

services:
  postgres:  # ... same as above
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD}

n8n-main:

    image: docker.n8n.io/n8nio/n8n

    restart: unless-stopped

    ports:

      - "5678:5678"

    environment:

      EXECUTIONS_MODE: queue

      DB_TYPE: postgresdb

      DB_POSTGRESDB_HOST: postgres

      DB_POSTGRESDB_DATABASE: n8n

      DB_POSTGRESDB_USER: n8n

      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}

      QUEUE_BULL_REDIS_HOST: redis

      QUEUE_BULL_REDIS_PASSWORD: ${REDIS_PASSWORD}

      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}

    depends_on: [postgres, redis]

n8n-worker:

    image: docker.n8n.io/n8nio/n8n

    restart: unless-stopped

    command: worker --concurrency=10

    environment:

      EXECUTIONS_MODE: queue

      DB_TYPE: postgresdb

      DB_POSTGRESDB_HOST: postgres

      DB_POSTGRESDB_DATABASE: n8n

      DB_POSTGRESDB_USER: n8n

      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}

      QUEUE_BULL_REDIS_HOST: redis

      QUEUE_BULL_REDIS_PASSWORD: ${REDIS_PASSWORD}

      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}

    depends_on: [postgres, redis]

    deploy:

      replicas: 2

Tuning tips:

• --concurrency=10: I/O-heavy workflows (HTTP/DB) → 10-20; CPU-heavy → 2-5, add more workers instead
• N8N_ENCRYPTION_KEY must be identical across main and all workers
• Binary data in Queue mode requires S3/MinIO external storage — filesystem sharing won't work
• docker compose up -d --scale n8n-worker=4 to scale

5.5 System Requirements

| Scenario | Configuration |
|----------|-------------|
| Personal / testing | 2 vCPU / 4GB RAM |
| Small production (1-2 workers) | 4 vCPU / 8GB RAM |
| High concurrency | 8+ vCPU / 16GB+ RAM |

6. Comparison with Alternatives

6.1 Feature Matrix

| Dimension | n8n | Zapier | Make | Activepieces | Power Automate |
|-----------|-----|--------|------|--------------|----------------|
| License | Fair-code (Sustainable Use) | Closed SaaS | Closed SaaS | MIT | Closed SaaS |
| Self-hosted | ✅ Free | ❌ | ❌ | ✅ Free | ❌ (partial) |
| Integrations | 1500+ | 7500+ | 1500+ | 200+ | 500+ (M365) |
| Code nodes | JS/Python | Paid only | Expressions | JS | Power Fx |
| AI/Agent | Native LangChain | AI Central | Basic AI steps | Catching up | Copilot |
| Queue scaling | ✅ Redis workers | ❌ | ❌ | ✅ | ❌ |
| Data privacy | Full control | Cloud | Cloud | Full control | Cloud/hybrid |

6.2 Pricing Comparison

| Platform | Entry price | Billing unit | Large-scale cost |
|----------|-------------|-------------|-----------------|
| n8n Cloud Starter | €20/mo (2500 executions) | Per execution | Self-hosted: $0 |
| n8n Cloud Pro | €50/mo (10000 executions) | Per execution | |
| n8n Business (self-hosted) | €667/mo (40000 executions) | Per execution | |
| n8n Community (self-hosted) | Free | Unlimited | $0 (server only) |
| Zapier Professional | $49/mo (2000 tasks) | Per step | Expensive (multi-step) |
| Make Core | $9/mo (10000 ops) | Per operation | Moderate |
| Activepieces (self-hosted) | Free | Unlimited | $0 (server only) |

Key insight: n8n charges per execution, not per step. A workflow with 20 nodes running once counts as 1 execution. Zapier would count the same as 20 tasks. This makes complex workflows dramatically cheaper on n8n.

7. Practical Workflow Examples

7.1 Beginner: GitHub Issue → Slack Notification

[GitHub Trigger (New Issue)] → [Slack (Send Message)]

• GitHub Trigger listens for issue.opened events
• Slack node uses {{ $json.title }} to push the issue title to a channel
• One execution per issue

7.2 Intermediate: AI Email Summarization

[Email Trigger (IMAP)] → [OpenAI (Summarize)] → [Slack (Notify)] → [Notion (Archive)]

• IMAP polls your inbox
• OpenAI node processes email body with prompt: "Summarize key points in 3 sentences"
• Slack notifies your team, Notion archives the summary
• Optional: Add an If node to route high-priority emails differently

7.3 Advanced: Multi-Step Data Pipeline with RAG

[Schedule (daily)] → [HTTP (fetch data)] → [Code (clean/transform)]
  → [Embeddings (vectorize)] → [Pinecone (store)]
  → [AI Agent (RAG Q&A)] → [Webhook (return result)]

• Scheduled trigger fetches external API data daily
• Code node (Python/JS) cleans and transforms
• Embeddings node generates vectors
• Stored in Pinecone vector database
• AI Agent with Memory + Pinecone Retriever answers queries via external webhook

8. Common Pitfalls and Best Practices

1. Encryption key drift: The most common silent failure in Queue mode — main and workers must share the same key
2. Binary data in Queue mode: Use S3/MinIO, not filesystem sharing
3. Worker concurrency: More isn't always better. CPU-heavy workflows need lower concurrency and more workers
4. Webhook sync bottleneck: For high throughput, use "respond immediately" to let workflows complete asynchronously
5. Execution log bloat: Configure EXECUTIONS_DATA_PRUNE to auto-clean old execution records
6. Pin image versions: Use specific tags (n8n:1.x.x) in production, not latest
7. Security hardening: Enable Basic Auth, disable ExecuteCommand node, restrict file access, firewall to only 80/443

9. Who Should Use n8n?

9.1 Ideal Use Cases

✅ Developers who need custom automation: Code nodes, custom integrations, and the ability to dig into the codebase
✅ Privacy-conscious organizations: Self-hosted, data never leaves your infrastructure
✅ AI/LLM-heavy workflows: Native LangChain integration is unmatched by competitors
✅ Complex multi-step automations: 20+ step workflows where Zapier's per-task pricing would be prohibitive
✅ High-volume automation: Queue mode scales to millions of executions per day

9.2 Where It Falls Short

❌ Non-technical teams: The learning curve is steeper than Zapier or Make
❌ Maximum integration coverage: Zapier's 7500+ integrations still dominate
❌ True open-source purists: The fair-code license means it's not truly open-source (MIT/Apache)
❌ Enterprise SaaS use: If you want to offer n8n as a service, you need a paid license

9.3 Alternatives at a Glance

| Tool | Best for |
|------|----------|
| Zapier | Non-technical teams, maximum integrations, simple two-step flows |
| Make | Complex visual logic, budget-conscious mid-size teams |
| n8n | Developers, AI/LLM agents, data privacy, large-scale self-hosted |
| Activepieces | MIT license, simpler than n8n, good for teams wanting true open source |
| Power Automate | Teams already deep in the Microsoft 365 ecosystem |

10. My Verdict

n8n's success is no accident. It sits at the perfect intersection of three major trends:

1. The self-hosting renaissance: As data privacy regulations tighten globally, organizations are reclaiming control over their infrastructure
2. AI-native automation: The LangChain integration makes n8n the "visual orchestration layer for AI agents" — a moat that Zapier and Make will struggle to cross
3. Developer-friendly design: Code nodes, clean monorepo architecture, plugin system — it respects developers rather than treating them as end-users

What makes it exceptional:

The AI/Agent capabilities are genuinely differentiated. No other automation platform lets you build a ReAct agent pipeline that autonomously decides which tools to call, all within a visual workflow editor. This is not a feature parity comparison — it's a category distinction.

The fair-code license is a practical compromise. For 99% of use cases (internal team automation, personal projects, even most commercial operations), it's functionally equivalent to free. The restriction only bites if you want to resell n8n as a service, which is a reasonable line for a sustainable project.

The execution model (per-execution, not per-step) is economically rational for complex workflows. A 20-step Zapier zap costs $49/month for 2000 runs. The same 20-step n8n workflow costs $0 (self-hosted) for unlimited runs.

The honest concerns:

The fair-code license requires clear communication. Teams evaluating n8n need to understand that it's not open-source in the MIT/Apache sense. If your organization has a strict "MIT only" policy, Activepieces is the alternative.

The learning curve is real. The visual editor is excellent, but configuring webhooks, expressions, and the queue mode requires understanding how n8n works under the hood. Non-technical users will struggle.

The integration count (1500+) is impressive but still trails Zapier's 7500+. For niche integrations, you may need to write a custom node.

Bottom line:

If you're a developer or technical team building automation with AI components, n8n is the best choice in 2026. The combination of self-hosting, native AI agents, and per-execution pricing creates a value proposition that no alternative matches. The fair-code license is a meaningful consideration, but for most use cases, it's a non-issue.

Try it:

• GitHub: https://github.com/n8n-io/n8n
• Docker: docker run -p 5678:5678 docker.n8n.io/n8nio/n8n
• Docs: https://docs.n8n.io
• Pricing: https://n8n.io/pricing