VPasCode: Ein praktischer Leitfaden zu Diagram-as-Code mit Visual Paradigm

Einführung

Softwarearchitekturen und Geschäftsprozesse lassen sich oft visuell besser verstehen als durch reinen Text oder Quellcode. Traditionelle Diagrammwerkzeuge können jedoch dazu führen, dass Diagramme schwer zu warten sind: Layouts erfordern manuelle Anpassungen, Änderungen sind schwer zu überprüfen, und die Zusammenarbeit hängt häufig vom Austausch von Bilddateien oder proprietären Projektdokumenten ab.

VPasCode, Abkürzung für Visual Paradigm als Code, löst diese Probleme durch einen browserbasierten Diagram-as-Code-Arbeitsablauf. Anstatt Formen manuell auf eine Zeichenfläche zu ziehen, beschreiben Benutzer Diagramme mit textbasierten Sprachen wie PlantUML, Mermaid und Graphviz. VPasCode rendert den Quellcode dann in Echtzeit als visuelles Diagramm. Es vereint einen Code-Editor, einen Diagramm-Renderer, KI-Unterstützung, Freigabefunktionen und Export-Tools in einem einzigen Arbeitsbereich.

Das Ergebnis ist ein Arbeitsablauf, der der Softwareentwicklung näher kommt: Diagramme können als Text erstellt, durch Code-Änderungen überprüft, in Versionskontrollsystemen gespeichert, bei Systemänderungen neu generiert und in der gesamten Dokumentation wiederverwendet werden.

Was ist Diagram-as-Code?

Diagram-as-Code, oder DaC, ist die Praxis, ein Diagramm mit einer textbasierten Sprache zu definieren, anstatt es manuell zu zeichnen.

Ein traditioneller Arbeitsablauf könnte Folgendes beinhalten:

1. Öffnen einer Diagramm-Anwendung.

2. Ziehen von Formen auf eine Zeichenfläche.

3. Manuelles Verbinden der Formen.

4. Neupositionieren von Objekten, wenn sich die Struktur ändert.

5. Exportieren eines Bildes für die Dokumentation.

Ein Diagram-as-Code-Arbeitsablauf ersetzt diese Schritte durch Quellcode:

flowchart LR
    User --> WebApp
    WebApp --> API
    API --> Database

Der Renderer wandelt diese Definition in ein visuelles Flussdiagramm um. Wenn sich die Architektur ändert, bearbeitet der Autor den Text, anstatt jedes Objekt manuell neu anzuordnen.

Dieser Ansatz bietet mehrere praktische Vorteile:

• Versionskontrolle:Diagramm-Definitionen können in Git zusammen mit Anwendungscode und Dokumentation gespeichert werden.

• Lesbare Änderungen:Überprüfer können Ergänzungen, Löschungen und Beziehungsänderungen durch normale Diffs einsehen.

• Wiederholbarkeit:Die gleiche Quelle kann das Diagramm konsistent neu generieren.

• Automatisierung:Diagramme können Teil der Dokumentation oder von Build-Pipelines werden.

• Schnellere Iteration:Strukturelle Änderungen erfordern in der Regel das Bearbeiten weniger Zeilen anstatt das Manipulieren vieler Formen.

VPasCode fasst diesen Workflow in eine einheitliche, browserbasierte Umgebung mit Live-Rendering und Unterstützung für mehrere Diagrammierungsstandards zusammen.

Die Rolle von VPasCode in Visual Paradigm

Visual Paradigm bietet ein breiteres Ökosystem für Softwaremodellierung, Unternehmensarchitektur, Dokumentation und visuelle Analyse. VPasCode ergänzt diese Werkzeuge, indem es einen leichten, textbasierten Einstiegspunkt bietet.

Es ist besonders nützlich, wenn ein Team Folgendes tun möchte:

• Schnell eine Architektur aus einer schriftlichen Beschreibung skizzieren.

• Diagramme nah an Quellcode und technischer Dokumentation halten.

• Ein System prototypisieren, bevor in ein vollständig angepasstes visuelles Modell investiert wird.

• Diagramme über KI generieren und das Ergebnis anschließend manuell verfeinern.

• Ein Live-Diagramm teilen, ohne große Projektdateien zu senden.

• Diagramme für Berichte, Präsentationen und Wikis exportieren.

• Von einem textbasierten Diagramm in den umfassenderen Modellierungs- und Dokumentationsworkflow von Visual Paradigm übergehen.

Die zentrale Idee ist nicht, dass Diagram-as-Code jede visuelle Modellierungsaufgabe ersetzt. Vielmehr bietet es Teams eine schnelle und wartbare Möglichkeit, Diagramme zu erstellen, während Visual Paradigm für detailliertere Modellierungs-, Dokumentations- und Präsentationsarbeiten weiterhin verfügbar bleibt.

Hauptkomponenten von VPasCode

Browserbasierter Code-Editor

VPasCode läuft in einem Webbrowser und eliminiert die Notwendigkeit einer lokalen Installation oder komplexen Einrichtung. Sein Editor ist für Diagramm-Quellcode konzipiert und verfügt über Funktionen wie Syntax-Hervorhebung, Zeilennummern, Einrückungsunterstützung und Echtzeit-Status-Feedback.

Ein typischer Workflow ist:

1. Öffnen Sie den VPasCode-Editor.

2. Wählen Sie die Diagrammsprache aus oder lassen Sie sie automatisch erkennen.

3. Geben Sie Diagrammcode ein oder fügen Sie ihn ein.

4. Überprüfen Sie das Live-gerenderte Ergebnis.

5. Korrigieren Sie die Syntax oder verfeinern Sie die Struktur.

6. Teilen oder exportieren Sie das fertige Diagramm.

Live-Vorschau-Leinwand

Das Vorschau-Fenster zeigt das gerenderte Diagramm an, während der Quellcode bearbeitet wird. Dieser nebeneinander angeordnete Workflow reduziert die Notwendigkeit, zwischen einem Editor und einem separaten Rendering-Tool zu wechseln.

Ein nützliches Erstellungsmuster besteht darin, in zwei Durchgängen zu arbeiten:

• Struktureller Durchgang:Knoten, Akteure, Komponenten und Beziehungen definieren.

• Präsentationsdurchgang:Richtung, Beschriftungen, Gruppierung, Themen und visuelles Styling anpassen.

Diese Trennung hilft Benutzern, sich zunächst auf die Korrektheit und anschließend auf die Lesbarkeit zu konzentrieren.

Mehrere Diagramm-Engines

VPasCode bringt mehrere Text-zu-Diagramm-Engines in einer einzigen Umgebung zusammen. Die primär unterstützten Formate umfassen PlantUML, Mermaid und Graphviz, wobei weitere Formate und Funktionen in der breiteren Plattform verfügbar sind.

Die beste Engine hängt vom Zielpublikum und dem Zweck des Diagramms ab. PlantUML ist oft angemessen, wenn formale UML- oder Architekturnotationen von Bedeutung sind. Mermaid ist praktisch für Markdown-basierte Dokumentation. Graphviz ist effektiv, wenn das Hauptproblem darin besteht, Beziehungen und Graphstrukturen darzustellen.

Grundkonzepte

Deklarative Diagrammdefinition

In einem deklarativen Workflow beschreibt der Autor, was das Diagramm enthält und wie seine Elemente miteinander in Beziehung stehen. Die Rendering-Engine bestimmt einen Großteil des Layouts.

Zum Beispiel:

@startuml
actor Kunde
participant "Webanwendung" as Web
participant "Zahlungsdienst" as Payment
database Bestellungen

Kunde -> Web: Bestellung einreichen
Web -> Payment: Zahlung autorisieren
Payment --> Web: Zahlung genehmigt
Web -> Bestellungen: Bestellung speichern
Web --> Kunde: Bestätigung anzeigen
@enduml

Der Code beschreibt Teilnehmer und Interaktionen, ohne dass der Autor Lifelines und Pfeile manuell zeichnen muss.

Quelle als einzige Quelle der Wahrheit

Die Diagrammquelle sollte als autoritative Darstellung des Modells behandelt werden. Exportierte PNG- oder PDF-Dateien sind nützliche Ausgaben, sollten aber nicht die einzige Kopie des Diagramms sein.

Eine empfohlene Projektstruktur könnte wie folgt aussehen:

architecture/
├── context/
│   └── system-context.puml
├── containers/
│   └── application-containers.mmd
├── deployment/
│   └── production-topology.dot
└── README.md

Dies erleichtert die Aktualisierung von Diagrammen, wenn sich das System ändert.

Live-Rendering

Live-Rendering bedeutet, dass sich die visuelle Ausgabe aktualisiert, wenn sich die Quelle ändert. Dies unterstützt schnelles Feedback: Fehlende Beziehungen, fehlerhafte Syntax und unklare Layouts werden während der Erstellung sichtbar, nicht erst nach dem Export.

Engine-Auswahl

Verschiedene Sprachen haben unterschiedliche Syntax, Layout-Algorithmen und unterstützte Diagrammtypen. Die frühzeitige Wahl einer Engine verhindert unnötiges Neuschreiben später.

Zum Beispiel:

• Verwenden Sie Mermaid für einen prägnanten Dienstfluss in einem Markdown-Dokument.

• Verwenden Sie PlantUML für ein detailliertes C4- oder UML-Modell.

• Verwenden Sie Graphviz für ein großes Abhängigkeitsnetzwerk.

• Verwenden Sie ein spezielles unterstütztes Format, wenn das Diagramm primär eine Mindmap, Datenvisualisierung oder eine andere nicht-UML-Darstellung ist.

KI-gestützte Erstellung

VPasCode enthält KI-orientierte Funktionen zum Generieren von Diagrammcode aus natürlichen Sprachanweisungen, zum Ändern bestehender Diagramme, zur Diagnose von Syntaxproblemen und zur Übersetzung von Beschriftungen. Einige erweiterte KI-Funktionen können von der verwendeten Visual Paradigm-Edition oder dem Abonnement abhängen.

KI ist am effektivsten, wenn die Anweisung Folgendes angibt:

• Den Diagrammtyp.

• Die beabsichtigte Notation oder Engine.

• Die Systemkomponenten.

• Die Beziehungen zwischen den Komponenten.

• Das gewünschte Detaillierungsgrad.

• Alle Anforderungen an das Zielpublikum oder das Format.

Zum Beispiel:

Erstellen Sie ein PlantUML C4-Komponentendiagramm für einen Online-Buchhandel. Beziehen Sie einen Kunden, eine Webanwendung, einen Katalogdienst, einen Bestelldienst, einen Zahlungsanbieter und eine PostgreSQL-Datenbank ein. Zeigen Sie die Hauptdatenflüsse und verwenden Sie klare Systemgrenzen.

KI-generierter Code sollte dennoch überprüft werden auf:

• Falsche Beziehungen.

• Fehlende Komponenten.

• Mehrdeutige Beschriftungen.

• Nicht unterstützte Syntax.

• Sicherheits- oder Architekturannahmen, die nicht im Prompt angegeben wurden.

Versionierbare visuelle Dokumentation

Ein textbasiertes Diagramm kann ähnlich wie Quellcode überprüft werden. Eine Änderung von:

WebApp --> Database

zu:

WebApp --> Cache
Cache --> Database

verdeutlicht klar, dass eine Caching-Schicht eingeführt wurde.

Dies macht Diagramme besser geeignet für:

• Pull-Requests.

• Architektur-Entscheidungsdokumente.

• Release-Dokumentation.

• Design-Überprüfungen.

• Compliance-Nachweise.

• Onboarding-Materialien.

Beispiele mit Visual Paradigm VPasCode

Beispiel 1: Drei-Schichten-Webanwendung

Mermaid ist eine praktische Wahl für einen einfachen Architekturablauf:

flowchart TB
    User[Benutzerbrowser]
    Web[Web-Frontend]
    API[Anwendungs-API]
    DB[(Relationale Datenbank)]

    User --> Web
    Web --> API
    API --> DB

Dieses Diagramm vermittelt die Hauptebenen, ohne dass detaillierte UML-Notation erforderlich ist. Es kann später um Authentifizierung, Caching, Warteschlangen oder externe Dienste erweitert werden.

Beispiel 2: Microservice-Anforderungsablauf

Ein Sequenzdiagramm ist nützlich, wenn Zeitabläufe und Interaktionen von Bedeutung sind:

@startuml
actor User
participant "Web-Client" as Client
participant "API-Gateway" as Gateway
participant "Bestellservice" as Orders
participant "Zahlungsservice" as Payments
database "Bestelldatenbank" as DB

User -> Client: Bestellung aufgeben
Client -> Gateway: POST /orders
Gateway -> Orders: Bestellung erstellen
Orders -> Payments: Zahlung autorisieren
Payments --> Orders: Genehmigt
Orders -> DB: Bestellung speichern
Orders --> Gateway: Bestellbestätigung
Gateway --> Client: 201 Created
Client --> User: Bestätigung anzeigen
@enduml

Dieses Beispiel kann Teams dabei helfen, API-Grenzen, synchrone Aufrufe, Zahlungsverhalten und Persistenz zu diskutieren.

Beispiel 3: Systemkontext mit PlantUML

PlantUML eignet sich gut für Hochlevel-Architekturen und C4-Stil-Diagramme:

@startuml
!include <C4/C4_Context>

Person(customer, "Kunde", "Gibt Bestellungen auf und verfolgt diese")
System(shop, "Online-Shop", "Bietet Produktübersicht und Checkout an")
System_Ext(payment, "Zahlungsanbieter", "Verarbeitet Kartenzahlungen")
System_Ext(email, "E-Mail-Dienst", "Sendet Bestellbenachrichtigungen")

Rel(customer, shop, "Verwendet")
Rel(shop, payment, "Verarbeitet Zahlungen über")
Rel(shop, email, "Sendet Benachrichtigungen über")

@enduml

Dieses Diagramm konzentriert sich auf Systemgrenzen und externe Beziehungen anstatt auf Implementierungsdetails.

Beispiel 4: Abhängigkeitsgraph mit Graphviz

Graphviz ist nützlich, um Abhängigkeiten darzustellen:

digraph Dependencies {
    rankdir=LR;

    Frontend -> APIGateway;
    APIGateway -> UserService;
    APIGateway -> OrderService;
    OrderService -> PaymentService;
    OrderService -> OrderDatabase;
    UserService -> UserDatabase;
}

Für ein großes Softwaresystem kann diese Art von Graph zentrale Dienste, Abhängigkeitsketten und potenzielle Kopplungsprobleme aufzeigen.

Beispiel 5: KI-gestützte Verfeinerung

Ein Team könnte mit einer Anfrage in natürlicher Sprache beginnen:

Erstellen Sie ein Mermaid-Architekturdiagramm für eine Kundenplattform mit Browser-Client, API-Gateway, Ticket-Dienst, Wissensdatenbank, Benachrichtigungsdienst und relationaler Datenbank.

Nach der Generierung könnte der Autor die KI bitten:

• Eine Nachrichtenwarteschlange zwischen dem Ticket-Dienst und dem Benachrichtigungsdienst hinzufügen.

• Backend-Dienste innerhalb einer Systemgrenze gruppieren.

• Beschriftungen für ein nichttechnisches Publikum umbenennen.

• Das Diagramm von Mermaid nach PlantUML konvertieren.

• Sichtbare Beschriftungen in eine andere Sprache übersetzen.

• Einen Fehler behebengemeldet vom Renderer.

Das wichtige Prinzip besteht darin, KI als Beschleuniger für die Modellierung zu betrachten, nicht als Ersatz für eine Architekturüberprüfung.

Ein empfohlener VPasCode-Arbeitsablauf

1. Definieren Sie den Zweck des Diagramms

Bevor Sie Code schreiben, entscheiden Sie, welche Frage das Diagramm beantworten soll.

Beispiele:

• Welche Systeme interagieren mit unserem Produkt?

• Wie bewegt sich eine Benutzeranfrage durch das Backend?

• Welche Dienste hängen von der Datenbank ab?

• Wie wird die Anwendung bereitgestellt?

• Welche geschäftlichen Schritte sind bei der Genehmigung einer Bestellung beteiligt?

Ein Diagramm mit einem klaren Zweck ist in der Regel leichter zu verstehen als ein Diagramm, das versucht, die gesamte Organisation oder das gesamte System darzustellen.

2. Wählen Sie die Diagramm-Engine

Wählen Sie je nach Zweck und Zielgruppe des Diagramms PlantUML, Mermaid, Graphviz oder ein anderes unterstütztes Format aus.

Zum Beispiel:

• Wählen Sie Mermaid für ein Diagramm, das in einem Markdown-Repository eingebettet ist.

• Wählen Sie PlantUML für ein formales UML- oder C4-Modell.

• Wählen Sie Graphviz für eine Abhängigkeitsanalyse.

• Wählen Sie ein spezialisiertes Format, wenn dessen Notation besser zum Thema passt.

3. Erstellen Sie die kleinste nützliche Version

Beginnen Sie mit den Hauptakteuren, Systemen und Beziehungen. Vermeiden Sie es, sofort jedes Implementierungsdetail hinzuzufügen.

Für ein Architekturdiagramm beginnen Sie mit:

• Benutzer.

• Hauptanwendungen.

• Wichtige externe Systeme.

• Primäre Datenbanken.

• Hauptkommunikationspfade.

Fügen Sie dann nur Details hinzu, wenn sie dazu beitragen, die beabsichtigte Frage des Diagramms zu beantworten.

4. Rendern und Validieren

Verwenden Sie die Live-Vorschau, um zu überprüfen:

• Ob die Syntax gültig ist.

• Ob das Diagramm lesbar ist.

• Ob die Pfeile in die richtige Richtung zeigen.

• Ob die Beschriftungen verständlich sind.

• Ob die Grenzen und Gruppierungen korrekt sind.

• Ob das Layout bei normaler Zoomstufe weiterhin nutzbar bleibt.

VPasCode bietet Syntax-Feedback und KI-gestützte Korrekturfunktionen für unterstützte Workflows.

5. Verfeinern Sie die visuelle Sprache

Sobald der Inhalt korrekt ist, verbessern Sie die Darstellung:

• Verwenden Sie konsistente Namen.

• Gruppieren Sie zusammengehörige Elemente.

• Reduzieren Sie sich kreuzende Linien.

• Verwenden Sie klare Bezeichnungen für Beziehungen.

• Verwenden Sie geeignete Themen oder Stile.

• Halten Sie den Detaillierungsgrad konsistent.

Das Ziel ist nicht, Dekoration hinzuzufügen. Das Ziel ist es, die Anstrengung des Lesers zu reduzieren.

6. Überprüfen Sie das Diagramm im Team

Teilen Sie das Diagramm mit Entwicklern, Architekten, Analysten oder Stakeholdern. Stellen Sie gezielte Fragen:

• Fehlt eine wichtige Komponente?

• Spiegelt der Fluss das tatsächliche Verhalten wider?

• Sind die Systemgrenzen korrekt?

• Sind einige Beziehungen irreführend?

• Kann ein neues Teammitglied das Diagramm verstehen?

Da die Quelle textbasiert ist, können vorgeschlagene Änderungen systematischer integriert und überprüft werden.

7. Exportieren oder verbinden Sie mit der Dokumentation

Wenn das Diagramm fertig ist, exportieren Sie es für die Verwendung in Berichten, Präsentationen, technischen Dokumenten oder internen Wikis. VPasCode unterstützt in seinen dokumentierten Workflows bild- und vektororientierte Ausgaben wie PNG, SVG und PDF. Es verbindet sich zudem mit den Dokumentationsfunktionen von Visual Paradigm, einschließlich OpenDocs.

Für die langfristige Wartung bewahren Sie den ursprünglichen Quellcode zusammen mit dem exportierten Bild auf.

Praktiken für Zusammenarbeit und Dokumentation

Bewahren Sie Diagramme in der Nähe der Systeme auf, die sie beschreiben

Speichern Sie Architekturdiagramme zusammen mit dem relevanten Codebase- oder Dokumentations-Repository. Dies erhöht die Wahrscheinlichkeit, dass Diagramme aktualisiert werden, wenn sich die Implementierung ändert.

Verwenden Sie aussagekräftige Dateinamen

Bevorzugen Sie Namen wie:

checkout-sequence.puml
production-deployment.mmd
service-dependencies.dot

Vermeiden Sie generische Namen wie diagram1 oder endgültige-Version.

Ansichten nach Zielgruppe trennen

Ein einzelnes Diagramm dient selten allen gleichermaßen gut. Erwägen Sie, separate Ansichten zu pflegen:

• Exekutiv-Kontextansicht:Wichtige Systeme und Geschäftsfähigkeiten.

• Architekturansicht:Dienste, Datenbanken und externe Abhängigkeiten.

• Entwickler-Sequenzansicht:Laufzeit-Interaktionen und API-Aufrufe.

• Betriebsansicht:Hosts, Cluster, Netzwerke und Bereitstellungsziele.

• Geschäftsprozessansicht:Aktivitäten, Entscheidungen und Übergaben.

Jede Ansicht kann aus Text generiert werden und dient dabei einem unterschiedlichen Kommunikationszweck.

Beschriften Sie Etiketten als Dokumentation

Diagrammetiketten sollten prägnant, aber aussagekräftig sein. „Service A“ mag technisch korrekt sein, aber „Bestellservice“ bietet Prüfern und Stakeholdern einen nützlicheren Kontext.

Diagramme während Architekturänderungen überprüfen

Ein Diagramm sollte aktualisiert werden, wenn:

• Ein wichtiger Dienst hinzugefügt oder entfernt wird.

• Eine Datenbank oder ein externer Anbieter sich ändert.

• Die Kommunikation asynchron wird.

• Eine Bereitstellungs-Topologie sich ändert.

• Eine öffentliche API oder ein Geschäftsprozess sich ändert.

Dies verhindert, dass das Diagramm zu einer veralteten Abbildung wird.

Vorteile und Einschränkungen

VPasCode ist besonders wertvoll für Teams, die bereits Git, Markdown, kontinuierliche Dokumentation oder Infrastructure-as-Code-Praktiken verwenden. Sein textbasiertes Workflow macht Diagramme einfacher zu reproduzieren, zu überprüfen und zu aktualisieren.

Es reduziert zudem die Fragmentierung von Werkzeugen, indem es mehrere Diagramm-Syntaxen in einem browserbasierten Editor zusammenführt. Die Möglichkeit, Live-Vorschauen, KI-Unterstützung, Exporte und Visual-Paradigm-Dokumentationsworkflows zu kombinieren, macht es in der Softwareentwicklung, der Unternehmensarchitektur und der Geschäftsanalyse nützlich.

Diagram-as-Code ist jedoch nicht automatisch die beste Option für jede Situation. Textbasierte Formate können eine Lernkurve aufweisen, und einige stark individualisierte Diagramme erfordern möglicherweise mehr manuelle visuelle Kontrolle, als ein deklarativer Engine bietet. Große Diagramme können zudem schwer zu warten werden, wenn die Quelle nicht in klare, fokussierte Ansichten unterteilt ist.

Eine praktische Strategie besteht darin, VPasCode für die schnelle, wartbare und versionskontrollierte Erstellung von Diagrammenund anschließend andere Visual-Paradigm-Funktionen nutzen, wenn tiefergehende Modellierung, Anpassung oder Dokumentationsverwaltung erforderlich ist.

Fazit

VPasCode bringt Softwareentwicklungsprinzipien in die visuelle Modellierung. Durch die Definition von Diagrammen mittels Text können Teams Architekturansichten, Prozessmodelle, Sequenzdiagramme, Abhängigkeitsgraphen und Dokumentationsvisualisierungen erstellen, die sich leichter versionieren, überprüfen, neu generieren und teilen lassen.

Die Unterstützung von PlantUML, Mermaid, Graphviz und anderen Formaten ermöglicht es Benutzern, die Notation auszuwählen, die am besten zu jedem Problem passt. Die Echtzeitdarstellung verkürzt den Feedback-Zyklus, während KI-Funktionen die initiale Generierung, Syntaxkorrektur, Modifikation und Übersetzung beschleunigen können. Die Integration in das breitere Visual-Paradigm-Ökosystem bietet einen Weg von schnellen textbasierten Skizzen zu reichhaltigeren Modellierungs- und Dokumentationsworkflows.

Der effektivste Weg, VPasCode zu nutzen, besteht darin, Diagramme als gewartete Projektassets und nicht als wegwerfbare Bilder zu betrachten: Definieren Sie einen klaren Zweck, wählen Sie den geeigneten Engine, halten Sie die Quelle unter Versionskontrolle, überprüfen Sie Änderungen mit dem Team und generieren Sie Exporte neu, sobald sich das System weiterentwickelt.

In dieser Rolle ist VPasCode mehr als ein Diagramm-Editor. Es ist eine Brücke zwischen Quellcode, KI-gestütztem Design, kollaborativer Architekturüberprüfung und professioneller visueller Modellierung.

Der Artikel ist auch in English, Español and فارسی verfügbar.