Diagramme – swark-Dokumentation

Wie swark PlantUML-, Mermaid- und Plotly-Diagramme erzeugt, welche Voraussetzungen nötig sind und wie eigene Diagramme eingebunden werden.

Überblick

Technik	Erzeugung	Verwendung in 0.2.1
PlantUML	serverseitig als PNG (Java, PlantUML-Jar aus dem Paket `jawira/plantuml`, Graphviz)	Strategie-Mindmap, Zonenmodell (C4), Baremetal-Übersicht, Cluster-Detail, Systemlandschaft, eigene Diagramme
Mermaid	im Browser (Skript von cdn.jsdelivr.net, Version 10)	nur Sandbox; in eigenen Blade-Dateien nutzbar
Plotly	im Browser (lokal ausgeliefert)	Netzdiagramm auf der Seite Findings

PlantUML

Ablauf

Eine Seite oder Blade-Datei enthält die Komponente x-swark-plantuml mit einer id.
Beginnt die id mit ~, sucht swark zuerst eine Datei im Content-Pfad (Ordner des Routennamens, Endung .plantuml oder .txt). Sonst wird der Text zwischen Start- und End-Tag der Komponente verwendet.
swark ergänzt @startuml und @enduml, ruft PlantUML auf und speichert das Bild unter storage/app/public/diagrams/<routen-ordner>/<id>_plantuml.png, dazu eine .sha-Datei mit dem Hash des Quelltexts.
Beim nächsten Aufruf wird das Bild nur neu erzeugt, wenn sich der Quelltext geändert hat.
Ausgeliefert wird das Bild über /storage/diagrams/...; unter dem Bild gibt es eine Schaltfläche «Show PlantUML code» mit dem Quelltext.

Kann das Bild nicht erzeugt werden, erscheint «Unable to render PlantUML: …» mit der Fehlermeldung bzw. «Unknown error», wenn keine Quelle gefunden wurde.

Voraussetzungen

Voraussetzung	Im Hosting Nerd-IT
Java-Laufzeit (`java` im Pfad)	Paket `default-jre-headless` im Image
Graphviz (`dot`) für Klassen-, Komponenten- und Deploymentdiagramme	Paket `graphviz` im Image
Schriften	Paket `fonts-dejavu-core` im Image
Symlink `public/storage` → `storage/app/public`	wird beim Start durch die Laravel-Automatik des Basis-Images angelegt (`AUTORUN_ENABLED=true`); manuell: `php artisan storage:link`
Schreibrecht auf `storage/app/public`	Volume `laravel_data`, Besitzer `www-data`

Das offizielle swark-Docker-Image enthält weder Java noch Graphviz; deshalb installiert das Nerd-IT-Dockerfile diese Pakete zusätzlich. PlantUML läuft lokal im Container; Diagramme werden nicht an einen externen PlantUML-Server geschickt.

Attribute der Komponente

Attribut	Bedeutung	Standard
`id`	Name des Diagramms; mit `~` am Anfang wird zusätzlich eine Datei im Content-Pfad gesucht	Pflicht
`extension`	Dateiendung für die Dateisuche	`plantuml`, dann `txt`
`caching`	`false` erzeugt das Bild bei jedem Aufruf neu	`true`

Eigene Diagramme

In einer Blade-Datei im Content-Pfad (Slot oder Hook):

<x-swark-plantuml id="netz-uebersicht">
nwdiag {
  network dmz {
    address = "10.0.10.0/24"
    web01 [address = "10.0.10.11"];
  }
  network core {
    address = "10.0.20.0/24"
    db01 [address = "10.0.20.21"];
  }
}
</x-swark-plantuml>

Mit Datei statt Inline-Text auf der Systemlandschaft: infrastructure/index/landscape.plantuml anlegen (siehe Kapitel Content). C4-Diagramme sind über die mitgelieferte Standardbibliothek von PlantUML möglich (!include <C4/C4_Container>).

In Markdown-Dateien lassen sich keine Diagramme einbetten, weil Markdown-Inhalte kein HTML und keine Komponenten ausführen. Dafür .blade.php verwenden.

Generierte Diagramme

Seite	Diagramm	Datengrundlage
Strategie-Übersicht	Mindmap Strategie → Ziele	neueste Strategie und ihre Ziele
IT-Architektur	C4: Zonen als Boundary, Akteure als Person, Zugriff als Rel	`logical_zone`, `actor_in_logical_zone`
Baremetal-Systeme	Provider → Region → AZ → Baremetal mit Host, Virtualisierer, Betriebssystem	`baremetal`, `managed_baremetal`, `host`
Cluster-Detail	Namespaces → Runtime/Host → Software:Version	`cluster_member`, `application_instance`

Cache leeren

Generierte Bilder liegen im Volume laravel_data unter app/public/diagrams/. Ein veraltetes Bild verschwindet automatisch, sobald sich der Quelltext ändert. Bei Problemen kann der Ordner gelöscht werden; er wird beim nächsten Aufruf neu befüllt:

rm -rf /var/www/html/storage/app/public/diagrams

Mermaid

Komponente x-swark-mermaid-js in einer Blade-Datei:

<x-swark-mermaid-js>
flowchart LR
  Internet --> B2X --> CORE
</x-swark-mermaid-js>

Mermaid wird im Browser von cdn.jsdelivr.net geladen. Ohne Internetzugang des Browsers oder bei blockierten Drittanbieter-Skripten erscheint nur der Quelltext.

Plotly

Komponente x-swark-plotly mit Attributen width und height; der Inhalt ist das Plotly-Daten-Array als JavaScript, optional mit den Slots options und config. Verwendet für das Netzdiagramm auf der Seite Findings; in eigenen Blade-Dateien ebenfalls nutzbar.