n8n im Überblick — Architektur, Item-Modell und Demo-Repo

Artikel 1 · Serie: Einstieg in n8n

Der Prolog hat das Warum geklärt: SAP-Investition, Mercedes-Rollout, Souveränität als Auswahlkriterium. Dieser Artikel beginnt das Wie. Was läuft wo, wenn ein Workflow ausgeführt wird? Was bedeutet es konkret, dass Daten als Items fließen? Wo liegt n8n im Spektrum der Integrationswerkzeuge, und was heißt die Sustainable Use License für produktive Self-Hoster? Am Ende steht das Demo-Repo auf Codeberg, Tag v0.1.

Editor, Engine, Task Runner

n8n ist eine Node.js-Anwendung. Ein docker compose up startet einen einzigen Prozess, der mehrere Rollen gleichzeitig übernimmt.

Der Editor ist ein React-Frontend, das der n8n-Prozess als statische Dateien ausliefert. Wer den Browser öffnet, sieht einen Canvas mit Knoten und Verbindungen. Alle Interaktionen dort kommunizieren per HTTP und WebSocket mit dem laufenden n8n-Prozess im Hintergrund. Der Editor ist kein eigenständiges System, sondern ein Interface für die Engine.

Die Execution Engine übernimmt, sobald ein Workflow ausgelöst wird. Sie liest das Workflow-JSON aus der Datenbank, traversiert den Knoten-Graph, koordiniert den Datenfluss zwischen Knoten und schreibt den Execution-Verlauf zurück. Das gesamte Workflow-Modell, also Knoten, Verbindungen, Parameter und Credential-Referenzen, liegt als JSON in Postgres. Es gibt keine Konfigurationsdatei für Workflows.

Die Task Runner sind seit n8n 2.0 ein eigener Architekturbestandteil. Wenn ein Code-Knoten JavaScript oder Python ausführt, passiert das nicht direkt im Hauptprozess, sondern in einem isolierten Runner. Der Hauptprozess enthält einen Task Broker, der Aufgaben über WebSocket an Runner-Prozesse delegiert. In der Standard-Konfiguration startet n8n den Runner als Child-Prozess (Internal Mode). In produktiven Setups mit mehreren parallelen Executions kann der Runner als Sidecar-Container betrieben werden (External Mode). Die Isolation hat konkrete Konsequenzen: Code-Knoten haben keinen Zugriff auf die Environment-Variablen des Host-Prozesses.

Workflows liegen als JSON in Postgres. Das hat eine praktische Konsequenz: sie sind exportierbar, versionierbar und in Git nachvollziehbar. Wer ein Workflow-JSON öffnet, sieht JSON-Objekte für jeden Knoten mit Parametern und Canvas-Positionen. Credential-Inhalte sind verschlüsselt in einer separaten Tabelle, im Workflow-JSON stehen nur Referenzen.

Ab n8n 2.0 gibt es Draft- und Publish-Zustände. Ein Workflow kann geändert werden, ohne dass die aktive Version berührt wird. Erst nach dem Publish-Schritt ist er live. In Artikel 7 kommt dieser Mechanismus im Kontext von Error Handling und Versionierung noch einmal.

Die n8n-Version, auf der diese Reihe aufbaut, ist 2.21.x (Stand: 2.21.4, Mai 2026).

Workflow, Knoten, Trigger, Verbindungen

Vier Begriffe bilden das Grundvokabular:

Ein Workflow ist eine benannte, versionierte Verarbeitungseinheit. Er hat genau einen Startpunkt, besteht aus beliebig vielen Knoten und endet entweder implizit im letzten Knoten oder explizit in einem Response-Knoten. Der gesamte Workflow liegt als JSON in der Datenbank und kann jederzeit exportiert werden.

Ein Knoten ist die Grundeinheit der Verarbeitung. Jeder Knoten hat Eingaben, Ausgaben und Parameter. Die wichtigsten Knoten-Kategorien:

Ein Trigger ist der Startknoten eines Workflows. Jeder Workflow hat genau einen. Mögliche Trigger: Webhook (eingehender HTTP-Request), Zeitplan (Cron), Datenbank-Event, manueller Aufruf oder Chat-Nachricht. Der Trigger bestimmt, wann der Workflow startet, und liefert die ersten Items in den Flow.

Verbindungen verbinden den Output eines Knotens mit dem Input des nächsten. Ein Knoten kann mehrere Outputs haben (ein Switch-Knoten verzweigt nach Bedingung) und mehrere Inputs empfangen (ein Merge-Knoten wartet auf mehrere Pfade).

Das Item-Array

Das ist die konzeptuelle Eigenheit von n8n, an der Einsteiger zuverlässig scheitern.

Jeder Knoten empfängt ein Array von Items und gibt ein Array von Items aus. Nicht ein einzelnes JSON-Objekt. Ein Array.

Ein Item hat diese Struktur:

{
  "json": {
    "id": "TKT-1042",
    "subject": "SAP-Login schlägt fehl nach Passwortreset",
    "priority": "high",
    "language": "de"
  },
  "binary": {},
  "pairedItem": { "item": 0 }
}

Wenn ein Webhook-Trigger einen eingehenden HTTP-Request empfängt, erzeugt er ein Array mit einem Item. Der Request-Body landet in json. Binäre Daten (Datei-Uploads) landen in binary. pairedItem trackt, aus welchem Input-Item das Output-Item erzeugt wurde.

Wenn ein HTTP-Request-Knoten eine Liste von zehn Tickets aus einer API holt, hat der Knoten danach zehn Items im Output. Der nächste Knoten, etwa ein Set-Knoten zum Anreichern der Tickets, verarbeitet alle zehn automatisch. Keine explizite Schleife nötig. Das ist die Intention: Knoten arbeiten auf Mengen.

Das typische Scheitern sieht so aus: Im Code-Knoten gibt der Entwickler return items[0].json zurück. Das funktioniert für das erste Item, kaputt ist es für alle weiteren. Die richtige Schreibweise:

return items.map(item => ({
  json: {
    ...item.json,
    category: "sap-basis"
  }
}));

Für Expressions in {{ }} gilt: n8n greift automatisch auf das aktuelle Item zu. {{ $json.subject }} gibt den Subject-Wert des aktuellen Items zurück. Das ist kein Widerspruch zum Array-Modell, sondern eine Kurzschreibweise, die der Editor für jeden durchlaufenden Item evaluiert.

Im Spektrum der Integrationswerkzeuge

Der Prolog hat vier Kategorien eingeordnet. Für die Reihe sind zwei Grenzen praktisch relevant.

Grenze nach oben: Cloud Integration Suite. Wo es um B2B-Protokolle (AS2, EDIFACT), mandantenfähige Umgebungen, Compliance-Audit-Logs auf Nachrichten-Ebene oder fachliche Recovery mit Status-Tracking geht, ist n8n das falsche Werkzeug. SAP CPI oder Edge Integration Cell übernehmen dort. Artikel 9 behandelt die Entscheidungskriterien im Detail.

Grenze nach unten: direkter Code. Wer komplexe Algorithmen, eigene Bibliotheken oder spezifisches Daten-Processing braucht, greift zu Python, Swift oder TypeScript direkt. Der Code-Knoten in n8n hat Einschränkungen: kein Zugriff auf das lokale Filesystem, keine beliebigen npm-Pakete, kein Netzwerk-Zugriff außerhalb von n8n-Credentials.

Dazwischen liegt ein großes Territorium: ereignisgesteuerte Datenflüsse zwischen Systemen, AI-Agent-Orchestrierung, Automatisierungen, die zu komplex für SaaS-Tools und zu operational für reine Code-Projekte sind. Genau dort hat n8n seinen Platz.

Sustainable Use License in der Praxis

n8n verwendet die Sustainable Use License (seit 2022, Nachfolger von Apache 2.0 mit Commons Clause). Der Begriff „fair-code" ist n8ns eigene Bezeichnung für das Modell, nicht ein offizieller Lizenztyp.

Für produktive Self-Hoster ist die relevante Aussage kurz:

Die Einschränkung betrifft ausschließlich den n8n-Server-Code selbst. Die Workflows, die man baut, die Daten, die durch n8n fließen, und die angebundenen Dienste sind davon nicht betroffen.

Community Edition reicht für alle Artikel dieser Reihe vollständig aus. Enterprise-Features (SSO, externes Secret-Management, RBAC mit Custom-Roles) sind kein Thema hier.

Das Demo-Repo

Das Codeberg-Repo rotecodefraktion/n8n-einstieg begleitet die Reihe. Pro Artikel gibt es einen Tag. Artikel 1 endet mit Tag v0.1.

git clone https://codeberg.org/rotecodefraktion/n8n-einstieg.git
cd n8n-einstieg
git checkout v0.1

Stand v0.1 enthält:

• README.md mit Reihen-Kontext, Tag-Übersicht v0.1 bis v1.0 und Setup-Voraussetzungen
• CLAUDE.md mit Repo-Konventionen (Sprache, Branch-Schema, Commit-Stil, Test-Anforderungen)
• .gitignore für Python, Docker, n8n-Volumes und IDE-Dateien
• LICENSE (MIT; das Demo-Repo selbst ist MIT-lizenziert, n8n unterliegt der Sustainable Use License)

Ab Artikel 2 kommt der eigentliche Stack dazu.

Der nächste Artikel: Self-Hosting mit Docker Compose

Artikel 2 zeigt das vollständige Self-Hosting-Setup: n8n mit PostgreSQL als Datenbank, Caddy als Reverse Proxy mit automatischem HTTPS, alle produktiv relevanten Environment-Variablen und eine erste Smoke-Test-Routine. Der wichtigste Grund für Postgres statt SQLite ist nicht Performance, sondern die vermiedene Migration: Wer mit SQLite startet und später wechseln will, verliert Zeit. Artikel 2 setzt Postgres von Anfang an, Tag v0.2.

→ Prolog: Warum n8n, warum jetzt → Artikel 2: Self-Hosting mit Docker Compose (erscheint demnächst)