breznflow/README.de.md

BreznFlow

🇬🇧 English version → README.md

---

BreznFlow ist ein WordPress-Plugin, das n8n-Automations-Workflows als interaktive SVG-Diagramme rendert — direkt in Beiträgen und Seiten. Workflow-JSON einfügen, und das Plugin erzeugt ein zoombares, klickbares Diagramm mit Node-Detail-Panel, automatischer Maskierung sensibler Daten und farbcodierten Node-Icons.

Keine externen Abhängigkeiten. Kein CDN. Kein Tracking. Vanilla JavaScript. Ein Shortcode: [breznflow id="X"].

---

Warum dieses Plugin existiert

n8n-Workflows sind mächtig, aber visuell teilen ist überraschend schwierig. Screenshots sind statisch und veralten schnell. Den n8n-Editor einzubetten ist unpraktisch. JSON in einen Blogpost kopieren ist unlesbar.

BreznFlow löst das, indem es den rohen JSON-Export in ein interaktives Diagramm verwandelt — die gleichen Nodes, die gleichen Verbindungen, aber als sauberes SVG innerhalb von WordPress gerendert. Leser können zoomen, pannen und jeden Node anklicken, um seine Parameter zu sehen.

Entwickelt in Passau, Bayern — für Donau2Space und NoSchmarrn.dev, wo n8n-Automationen regelmäßig dokumentiert werden und eine bessere Darstellung brauchten.

---

Inhaltsverzeichnis

• Warum dieses Plugin existiert
• Verzeichnisstruktur
• Features
• Datenspeicherung
• Sicherheit
• Shortcode
• Installation
• Technischer Stack
• Lizenz

---

Verzeichnisstruktur

breznflow/
├── breznflow.php                 # Plugin-Header, Konstanten (BREZNFLOW_VERSION, BREZNFLOW_DIR, BREZNFLOW_URL)
├── uninstall.php                 # Aufräumen bei Plugin-Löschung
├── readme.txt                    # WordPress.org Plugin-Readme
├── assets/
│   ├── admin.css                 # Admin-Stylesheet (Wizard, Settings, Listtable)
│   ├── admin.js                  # Admin-JavaScript (Wizard-Schritte, JSON-Validierung)
│   ├── renderer.css              # Frontend SVG-Renderer Styles
│   ├── renderer.js               # Frontend-Renderer (SVG-Engine, Pan/Zoom, Detail-Panel)
│   ├── brezn.css                 # Legacy Brezn-Theme (Kompatibilität)
│   └── themes/
│       ├── dark.css              # Dark-Theme (Standard)
│       ├── light.css             # Light-Theme
│       ├── minimal.css           # Minimal-Theme
│       ├── tech.css              # Tech-Theme
│       └── brezn.css             # Brezn-Theme
├── includes/
│   ├── Core.php                  # Singleton-Bootstrap, lädt alle Abhängigkeiten
│   ├── PostType.php              # CPT breznflow_workflow + Taxonomie breznflow_category
│   ├── Shortcode.php             # [breznflow] Shortcode mit 13 Attributen
│   ├── DownloadHandler.php       # JSON-Download-Endpunkt (?breznflow_download={id})
│   ├── EmbedHandler.php          # Standalone Embed-Seite (?breznflow_embed={id})
│   ├── Admin/
│   │   ├── AdminMenu.php         # Menüstruktur + Dashboard-Render
│   │   ├── SettingsPage.php      # Plugin-Einstellungen (16 Optionen, validiert)
│   │   ├── ThemesPage.php        # Theme-Verwaltung (Import/Löschen eigener Themes)
│   │   ├── WizardPage.php        # 3-Schritt Import-Wizard (Einfügen/Upload → Konfigurieren → Vorschau)
│   │   ├── WorkflowListTable.php # WP_List_Table für Workflow-Verwaltung
│   │   └── views/                # PHP-Templates für alle Admin-Seiten
│   ├── Features/
│   │   ├── NodeTypeRegistry.php  # 86 Node-Typen mit Markenfarben und Icons
│   │   ├── NodeCategorizer.php   # Kategorisiert Nodes (Trigger, Action, Logic, AI, etc.)
│   │   ├── InfoBoxBuilder.php    # „3× HTTP Request, 2× Code" Node-Zusammenfassung
│   │   ├── ViewCounter.php       # View-Zähler pro Workflow
│   │   ├── RelatedWorkflows.php  # Ähnliche Workflows nach gemeinsamen Node-Typen
│   │   ├── ThemeRegistry.php     # 5 Built-in-Themes + Custom-Theme-Support
│   │   └── ThemeImporter.php     # Import/Export von .breznflow.json Theme-Dateien
│   └── Security/
│       ├── MaskingRules.php      # Secret-Erkennung (URL-Parameter, Header, Entropie)
│       ├── WorkflowValidator.php # JSON-Schema-Validierung für n8n-Exporte
│       └── WorkflowSanitizer.php # Zwei-Pass-Sanitierung: Strings + Secret-Maskierung
└── languages/
    ├── breznflow.pot             # Übersetzungsvorlage
    ├── breznflow-de_DE.po        # Deutsche Übersetzung
    └── breznflow-de_DE.mo        # Kompilierte deutsche Übersetzung

---

Features

Interaktiver SVG-Renderer

Das Herzstück von BreznFlow. Jeder n8n-Node wird zu einem klickbaren SVG-Element mit farbcodierten Icons, Verbindungslinien und Labels. Der Renderer unterstützt:

• Pan & Zoom — Mausrad zoomt zur Cursorposition, Klick-Drag zum Verschieben
• Node-Klick — öffnet das Detail-Panel unterhalb des Diagramms mit allen Node-Parametern
• Auto-Fit — Workflows über einem konfigurierbaren Node-Schwellenwert (Standard: 30) zoomen automatisch zum Trigger-Node beim Laden
• Minimap — optionales Minimap-Overlay zur Navigation in großen Workflows
• Vollbild — Portal-basierter Vollbildmodus

Alles wird clientseitig in Vanilla JavaScript gerendert — kein Canvas, kein WebGL, keine externen Bibliotheken.

---

3-Schritt Import-Wizard

1. Einfügen oder hochladen — JSON direkt einfügen, .json-Datei hochladen oder von URL abrufen
2. Konfigurieren — Darstellungsmodus, Theme, Zoom, Titel, Kategorien einstellen
3. Vorschau — Live-SVG-Vorschau mit Maskierungs-Zusammenfassung vor dem Veröffentlichen

Der Wizard validiert JSON gegen das n8n-Schema, sanitiert alle Strings und maskiert erkannte Geheimnisse. Das Maskierungs-Protokoll zeigt genau, was entfernt wurde und warum.

Import von URL: Ruft Workflow-JSON von beliebigen öffentlichen URLs per wp_remote_get() ab. Anfragen an private/interne Netzwerkadressen (localhost, LAN-Bereiche, Cloud-Metadaten-Endpunkte) werden blockiert.

---

Node Type Registry

86 vordefinierte Node-Typen mit markengetreuen Farben und 2-Buchstaben-Icons:

Kategorie	Beispiele
Trigger	Schedule, Webhook, Manual, Form
Kernlogik	HTTP Request, Code, IF, Switch, Merge, Filter
Datentransformation	HTML, XML, Markdown, Crypto
Datenbanken	MySQL, PostgreSQL, Redis, MongoDB, SQLite, Supabase
Kommunikation	Slack, Telegram, Discord, Gmail, WhatsApp
Google	Sheets, Drive, Calendar, Docs, YouTube
Dev-Tools	GitHub, GitLab, Jira, Confluence, Linear, Notion
KI	OpenAI, Claude, Gemini, Ollama, Hugging Face, Mistral, LangChain
Speicher	FTP, SSH, Airtable, Baserow
CRM/Marketing	HubSpot, Salesforce, Mailchimp, Brevo

Unbekannte Node-Typen bekommen einen deterministischen Fallback: 2-Buchstaben-Initialen und eine Farbe aus einem djb2-Hash — der gleiche unbekannte Typ sieht immer gleich aus.

---

Theme-System

5 Built-in-Themes: Dark (Standard), Light, Minimal, Tech, Brezn.

Eigene Themes können als .breznflow.json-Dateien mit 41 CSS-Farbtokens importiert werden. Custom-Themes werden in wp_options gespeichert und als Inline-CSS-Variablen gerendert.

Themes sind global, pro Workflow oder pro Shortcode wählbar via theme="dark".

---

Action Bar

Unterhalb des Diagramms (nicht im Compact-Modus) bietet die Action Bar:

Aktion	Steuerung	Funktion
Share	Globale Einstellung	Zeigt Artikel-Link + Anker-Link für Hash-Navigation
Embed	Global + pro Post	Zeigt iframe-Embed-Code für Standalone-Einbettung
Get JSON	Globale Einstellung	Zeigt formatiertes JSON mit Größe in KB
Download	Global + pro Post	Lädt sanitiertes JSON als Datei herunter

Jede Aktion ist global in den Einstellungen steuerbar und per Shortcode überschreibbar.

---

Maskierung sensibler Daten

BreznFlow speichert nie das rohe Workflow-JSON. Vor dem Speichern läuft eine Zwei-Pass-Sanitierung:

Pass 1 — String-Sanitierung: Alle Strings durchlaufen sanitize_text_field(). Ausnahme: jsCode-Felder bleiben erhalten, werden aber mit esc_html() ausgegeben (nie ausgeführt).

Pass 2 — Secret-Erkennung:

• URL-Parameter: api_key, token, secret, password, access_token, auth, client_secret in Query-Strings → [REDACTED]
• Header-Werte: Authorization, Bearer, X-API-Key und ähnliche Header-Namen in {name, value}-Paaren → Wert maskiert
• Hochentropie-Bedingungen: Werte in IF/Switch-Conditions, die UUID-Muster, Groß-/Kleinschreibung+Ziffern oder lange Strings ohne Leerzeichen matchen → per Entropie-Heuristik maskiert

Ein Maskierungs-Protokoll zeichnet jedes maskierte Element mit Grund, Key und Hinweis auf — sichtbar in der Wizard-Vorschau (Schritt 3).

---

Darstellungsmodi

Modus	Was angezeigt wird
visual	Vollständiges Diagramm mit Toolbar, Detail-Panel, Action Bar
info	Nur Node-Zähler (InfoBox) — kein Diagramm
compact	Diagramm ohne Toolbar und Action Bar

Konfigurierbar global, pro Workflow oder pro Shortcode.

---

Embed-Handler

Liefert eine Standalone-HTML-Seite unter ?breznflow_embed={id} für iframe-Einbettung. Die Seite enthält nur den SVG-Renderer — kein WordPress-Theme, keine Admin-Bar.

Dual-Gate-Sicherheit: Sowohl die globale allow_embed-Einstellung als auch das Per-Post-Meta _breznflow_show_embed müssen aktiviert sein.

URL-Parameter: ?theme={id} und ?minimap=0|1.

HTTP-Header enthalten X-Robots-Tag: noindex, nofollow und entfernen X-Frame-Options für Embedding.

---

Weitere Features

• View-Zähler — zählt, wie oft jeder Workflow angezeigt wird
• Ähnliche Workflows — zeigt verwandte Workflows nach gemeinsamen Node-Typen
• InfoBox — kompakte Zusammenfassung wie „3× HTTP Request, 2× Code, 1× OpenAI"
• KI-Erkennung — erkennt und markiert automatisch Workflows mit KI-Nodes
• Schema.org HowTo — optionale JSON-LD-Strukturdatenausgabe
• Anker-Navigation — <span id="breznflow-{id}"> für Hash-basiertes Deep-Linking mit 60px Scroll-Offset

---

Datenspeicherung

WordPress Options (wp_options)

Option-Key	Inhalt
breznflow_settings	Alle Plugin-Einstellungen (16 Keys, serialisiertes Array)
breznflow_custom_themes	Custom-Theme-Definitionen (serialisiertes Array)

Post Meta (wp_postmeta)

Meta-Key	Inhalt
_breznflow_raw_json	Sanitiertes Workflow-JSON (nie das Roh-Original)
_breznflow_original_name	Originaler Workflow-Name aus n8n
_breznflow_node_count	Gesamtzahl der Nodes
_breznflow_node_summary	Kategorisierte Node-Anzahl (JSON)
_breznflow_has_ai_nodes	Ob der Workflow KI-Nodes enthält
_breznflow_ai_node_types	Liste der KI-Node-Typen (JSON)
_breznflow_mask_log	Maskierte Werte beim Import (JSON)
_breznflow_default_zoom	Zoom-Level pro Workflow (10–200)
_breznflow_show_title	Titel anzeigen
_breznflow_show_infobox	InfoBox anzeigen
_breznflow_show_download	Download erlauben
_breznflow_show_embed	Einbettung erlauben
_breznflow_show_minimap	Minimap anzeigen
_breznflow_default_mode	Darstellungsmodus
_breznflow_default_theme	Theme-ID

Uninstall-Cleanup

uninstall.php löscht bei Plugin-Deinstallation:

• Alle breznflow_workflow-Posts und deren Meta
• Option breznflow_settings
• Alle breznflow_category-Taxonomie-Terms
• Alle Transients mit Präfix breznflow_

---

Sicherheit

Eingabevalidierung

• Workflow-JSON wird vor dem Import gegen das n8n-Schema validiert
• Alle $_POST / $_GET-Werte über wp_unslash() + spezifische Sanitizer verarbeitet
• Alle Ausgaben escaped mit esc_html, esc_attr, esc_url
• SQL-Queries ausschließlich via $wpdb->prepare()

CSRF-Schutz

Jede Admin-Aktion validiert eine WordPress-Nonce. Capability-Checks erfordern manage_options für Einstellungen und edit_posts für Workflow-Verwaltung.

Download- & Embed-Sicherheit

Beide Endpunkte validieren:

1. Post existiert, ist Typ breznflow_workflow und Status publish
2. Die entsprechende Per-Post-Meta-Berechtigung ist aktiviert
3. Die globale Einstellung ist aktiviert
4. Das gespeicherte JSON ist valide

Response-Header enthalten X-Content-Type-Options: nosniff. Downloads nutzen Cache-Control: no-store.

Import von URL

Das „Von URL abrufen"-Feature im Wizard blockiert Anfragen an private/interne Netzwerkadressen (localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, Cloud-Metadaten-Endpunkte) zur Verhinderung von SSRF-Angriffen.

---

Shortcode

[breznflow id="42"]
[breznflow id="42" mode="compact" theme="light" zoom="80"]
[breznflow id="42" show_share="0" show_embed="1" show_minimap="0"]

Attribut	Standard	Beschreibung
id	—	Workflow-Post-ID (erforderlich)
mode	visual	visual, info oder compact
theme	dark	Theme-ID
zoom	100	Initiales Zoom-Level (10–200)
show_title	true	Workflow-Titel anzeigen
show_infobox	true	Node-Zusammenfassung anzeigen
show_minimap	true	Minimap-Overlay anzeigen
show_download	false	Download-Button anzeigen
show_share	true	Share-Aktion anzeigen
show_embed	false	Embed-Aktion anzeigen
show_get_json	false	„Get JSON"-Aktion anzeigen
max_code_lines	50	Max. Zeilen in Code-Node-Anzeige

Auflösungs-Hierarchie: Shortcode-Attribut → Post-Meta → Plugin-Einstellungen.

---

Installation

Via GitHub Release (empfohlen):

1. breznflow.zip vom neuesten Release herunterladen
2. In WordPress unter Plugins → Installieren → Plugin hochladen einspielen

Manuell (clone):

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/noschmarrn/breznflow.git
wp plugin activate breznflow

Nach der Aktivierung:

1. BreznFlow → Workflow hinzufügen
2. n8n Workflow-JSON einfügen (oder .json-Datei hochladen)
3. Darstellungseinstellungen konfigurieren und Vorschau prüfen
4. Veröffentlichen — [breznflow id="X"] in beliebigen Beitrag oder Seite einfügen

Kein Build-Step. Alle Assets sind direkte JS/CSS-Dateien.

---

Technischer Stack

Komponente	Technologie
Backend	PHP 8.0+, WordPress Plugin API
Namespace	BreznFlow\
Architektur	Singleton-Core, Feature-Klassen mit register()
Rendering	Vanilla JavaScript SVG-Generierung (kein Canvas, keine Bibliotheken)
Datenbank	WordPress Options API + Post Meta
Caching	WordPress Transients (Related Workflows)
Frontend	Vanilla JS, kein Build-Step, kein externes CDN
I18n	.pot-File, Text-Domain breznflow
Coding Standard	WordPress PHPCS
Lizenz	GPL-2.0-or-later

---

Lizenz

GPL-2.0-or-later — https://www.gnu.org/licenses/gpl-2.0.html

Copyright (c) 2025–2026 Donau2Space