# BreznFlow

![PHP 8.0+](https://img.shields.io/badge/PHP-8.0%2B-blue)
![WordPress 6.0+](https://img.shields.io/badge/WordPress-6.0%2B-21759b)
![License: GPL-2.0](https://img.shields.io/badge/License-GPL--2.0--or--later-green)
![Version](https://img.shields.io/badge/Version-1.0.1-orange)

🇬🇧 [English version → README.md](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 [mifupa.com](https://mifupa.com), einem persönlichen Blog, auf dem regelmäßig n8n-Automationen vorgestellt werden und eine bessere Darstellung brauchten.

---

## Inhaltsverzeichnis

- [Warum dieses Plugin existiert](#warum-dieses-plugin-existiert)
- [Verzeichnisstruktur](#verzeichnisstruktur)
- [Features](#features)
- [Datenspeicherung](#datenspeicherung)
- [Sicherheit](#sicherheit)
- [Shortcode](#shortcode)
- [Installation](#installation)
- [Technischer Stack](#technischer-stack)
- [Lizenz](#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](https://github.com/noschmarrn/breznflow/releases/latest) herunterladen
2. In WordPress unter *Plugins → Installieren → Plugin hochladen* einspielen

**Manuell (clone):**
```bash
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](https://www.gnu.org/licenses/gpl-2.0.html)

Copyright (c) 2025–2026 [mifupa.com](https://mifupa.com)