# 12 — Workflow-Architektur

> Ein Workflow der funktioniert ist gut.
> Ein Workflow den jemand anderes (oder du in 6 Monaten) versteht, ist besser.

---

## Warum Architektur in n8n?

Kleine Workflows brauchen keine Architektur. Ein Webhook, drei Nodes, fertig.

Aber wenn Workflows wachsen — dutzende Nodes, mehrere Teams, täglich in Produktion — entscheiden Namenskonventionen, Modularität und Dokumentation darüber ob jemand den Workflow in 20 Minuten versteht oder in 2 Stunden.

---

## Naming Conventions

### Workflow-Namen
Schlechte Namen: `Webhook 1`, `Test`, `New workflow (3)`  
Gute Namen: `[Slack] User-Onboarding Notification`, `[Daily] Invoice Report Generation`

Pattern: `[Kanal/Trigger] Beschreibung der Aufgabe`

### Node-Namen
Standard-Node-Namen sind generisch: `HTTP Request`, `HTTP Request1`, `HTTP Request2`.  
Renamed: `GET: User Profile`, `POST: Send Invoice`, `PATCH: Update Status`

Pattern: `VERB: Was der Node tut`

Das macht Expressions lesbarer:
```js
// Unleserlich:
$node["HTTP Request3"].json.id

// Lesbar:
$node["GET: User Profile"].json.id
```

---

## Sub-Workflows: Modularisierung

Wenn du dieselbe Logik in mehreren Workflows wiederverwendest, pack sie in einen Sub-Workflow.

**Trigger:** Execute Workflow Trigger (kein Webhook, kein Schedule — nur intern aufrufbar)  
**Aufruf:** Execute Workflow Node im rufenden Workflow

Typische Sub-Workflow-Kandidaten:
- Authentifizierung/Token-Refresh
- Fehler-Notification (Slack/Email Alert)
- Standardisierte Datentransformation
- Gemeinsame API-Calls (z.B. zentrales CRM-Interface)

```
[Main Workflow]
    ↓
[Execute Workflow: "Send Alert"]
    ↓ (übergibt: error_message, workflow_name)
[Main continues after sub-workflow completes]
```

Sub-Workflows können Daten zurückgeben — der Execute Workflow Node empfängt den Output.

**Datenisolierung: Was nicht automatisch fließt**

Sub-Workflows laufen in einem eigenen Execution-Kontext. Nichts aus dem rufenden Workflow ist automatisch verfügbar — nicht `$json`, nicht Credentials, nicht Umgebungsvariablen.

Was du explizit übergeben musst:
- Alle Daten die der Sub-Workflow braucht → als Input-Items im Execute Workflow Node
- Credentials → im Sub-Workflow neu konfigurieren (nicht vom Parent geerbt)
- Workflow-weite Variablen → als Felder im Input mitschicken

Häufiges Symptom: Sub-Workflow läuft erfolgreich, gibt aber leere oder falsche Daten zurück — weil er still auf `$json` zugegriffen hat das im Parent existierte, im eigenen Kontext aber nicht.

```
// Parent übergibt explizit:
[Execute Workflow]
  Input: { "userId": $json.id, "email": $json.email }

// Sub-Workflow empfängt:
$json.userId  ✓
$json.email   ✓
$json.anderesFeldAusParent  ✗ — nicht verfügbar
```

---

## Sticky Notes: Inline-Dokumentation

n8n hat Sticky Notes — gelbe Post-Its direkt im Workflow-Canvas.

Nutze sie für:
- Erklärung warum ein Node so konfiguriert ist (nicht was er tut — das sieht man)
- Hinweise auf externe Abhängigkeiten ("API-Key muss monatlich rotiert werden")
- Aufgaben die noch offen sind ("TODO: Rate-Limiting einbauen")
- Kontext für komplexe Expressions ("Diese Formel normalisiert UTC auf Berlin-Zeit")

Sticky Notes kosten nichts. Ein Workflow ohne Sticky Notes in komplexen Bereichen ist technische Schuld.

---

## Workflow-Struktur: Horizontal denken

n8n läuft von links nach rechts. Nutze das.

**Anti-Pattern:** Lange vertikale Verschachtelungen, Nodes die kreuz und quer verbunden sind.  
**Besser:** Klare horizontale Flows mit Verzweigungen nach unten.

```
[Trigger] → [Parse] → [Validate] → [If: valid]
                                         ├─ true  → [Process] → [Store] → [Notify]
                                         └─ false → [Log Error] → [Alert]
```

Wenn ein Workflow zu breit wird: Sub-Workflow auslagern.

---

## Environments: Test vs. Production

Auf Self-Hosted n8n: Eine Instanz für Test, eine für Production.  
Auf n8n Cloud: Staging-Workflow neben Production-Workflow möglich.

Credentials für Test-APIs vs. Production-APIs trennen — niemals mit Produktionsdaten testen.

---

## Versionierung

n8n Workflows lassen sich als JSON exportieren — und das ist robuster als es klingt. JSON-Exporte sind vollständig, menschenlesbar und diff-fähig in Git.

**Einfacher Workflow-Git-Prozess:**
1. Workflow exportieren (Menu → Download)
2. In einem dedizierten Repo speichern: `workflows/[name].json`
3. Commit mit Beschreibung: `feat: Webhook-Auth hinzugefügt`
4. Bei Fehler: alten JSON reimportieren — sofortiges Rollback

Das deckt 90% der Versionierungsanforderungen. Für Teams mit mehreren Entwicklern und komplexeren CI/CD-Anforderungen bietet n8n Enterprise eine native Git-Integration.

Zusätzliche Orientierung im laufenden Betrieb:
- Naming Convention: `v2_WorkflowName` bei Major-Refactors als schnelle Orientierung
- Execution-History: de facto Audit-Log der letzten N Runs — wann hat was funktioniert

---

## Checkliste: Produktionsreifer Workflow

- [ ] Workflow hat aussagekräftigen Namen
- [ ] Alle Nodes sind sinnvoll benannt
- [ ] Komplexe Nodes haben Sticky-Note-Kommentar
- [ ] Error-Handling eingebaut (→ [Seite 08](08-error-handling.md))
- [ ] Error Workflow konfiguriert
- [ ] Keine API-Keys hardcoded (→ [Seite 09](09-credentials-auth.md))
- [ ] Webhooks mit Auth abgesichert
- [ ] Mit realen Test-Daten getestet (nicht nur synthetischen)
- [ ] Retry-Logik für flakige API-Calls
- [ ] Memory-Limits berücksichtigt (SplitInBatches bei großen Datasets)

---

**Zurück zum Wiki:** [Index](index.md)  
**Ressourcen:** [Community & Links](resources.md)