VPasCode ist eine browserbasierte Diagram-as-Code-Plattform, die einen Texteditor, Live-Rendering, mehrere Diagrammsprachen und KI-gestützte Generierung und Bearbeitung kombiniert. Sie unterstützt PlantUML, Mermaid, Graphviz, D2 und weitere Formate in einem einzigen Arbeitsbereich. Die Plattform kann Diagrammcode aus natürlichen Sprachanweisungen generieren, bestehenden Code bearbeiten, bei der Diagnose von Syntaxfehlern helfen, Beschriftungen übersetzen und Diagramme als SVG, PNG oder PDF exportieren.

Dieser Leitfaden erläutert, wie VPasCode als KI-gestützter Modellierungsworkflow für Softwarearchitektur, Prozesse, Abhängigkeiten, UML und technische Dokumentation verwendet wird.

1. Was ist Diagram-as-Code?

Diagram-as-Code ist die Praxis, ein Diagramm durch Text zu definieren, anstatt Formen manuell auf eine Zeichenfläche zu ziehen.

Anstatt:

1. Formen manuell hinzuzufügen

2. Sie mit Linien zu verbinden

3. Sie nach jeder Änderung neu zu positionieren

4. Ein statisches Bild zu exportieren

pflegen Sie eine Textdatei, die das Diagramm beschreibt:

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

Das Diagramm wird anschließend automatisch von einer Rendering-Engine erstellt.

Dieser Ansatz bietet mehrere Vorteile:

• Die Diagrammquelle kann in Git gespeichert werden.

• Änderungen können als Text-Diffs überprüft werden.

• Diagramme können konsistent neu generiert werden.

• KI kann den Quellcode erstellen oder ändern.

• Dokumentation kann zusammen mit dem Anwendungscode aktualisiert werden.

• Das gleiche Modell kann häufig in mehrere Formate exportiert werden.

• Große Diagramme sind einfacher zu refaktorisieren als manuell gezeichnete Diagramme.

VPasCode bietet einen einheitlichen Editor und eine Live-Vorschau für mehrere Diagram-as-Code-Standards und reduziert so die Notwendigkeit, zwischen separaten Tools zu wechseln.

2. Warum KI zu Diagram-as-Code hinzufügen?

Traditionelles Diagram-as-Code ist effizient, sobald Sie die Syntax kennen, erfordert aber dennoch:

• Das Erlernen sprachspezifischer Grammatiken

• Das Behalten von Layout- und Gestaltungsoptionen

• Das Debuggen von Syntaxfehlern

• Konvertierung zwischen Diagrammformaten

• Diagramme auch bei wachsender Größe lesbar halten

• Übersetzung von Beschriftungen für verschiedene Zielgruppen

KI kann in jeder Phase unterstützen:

Idee in natürlicher Sprache
        ↓
KI-generierter Diagrammcode
        ↓
Live-Vorschau
        ↓
Menschliche Prüfung
        ↓
KI-unterstützte Verfeinerung
        ↓
Versionskontrollierte Dokumentation

Beispielsweise können Sie folgenden Prompt eingeben:

Erstellen Sie ein Mermaid-Architekturdiagramm für ein E-Commerce-System mit einem Browser-Client, einem API-Gateway, einem Produktdienst, einem Auftragsdienst, einem Zahlungsanbieter, einer Nachrichtenwarteschlange und einer PostgreSQL-Datenbank. Zeigen Sie synchrone und asynchrone Kommunikation.

Die KI kann ein erstes Mermaid-Skript erstellen, das Sie sofort im VPasCode-Editor überprüfen und verfeinern können.

Die für VPasCode beschriebenen KI-Funktionen umfassen die Generierung von Diagrammen aus natürlicher Sprache, die Bearbeitung bestehender Skripte, die Unterstützung bei Syntaxfehlern und die Übersetzung von Diagrammbeschriftungen. Die Verfügbarkeit erweiterter KI-Funktionen kann von der Visual Paradigm-Edition oder dem Abonnement abhängen.

3. Die Rolle von VPasCode

VPasCode ist als zentraler Arbeitsbereich für drei zusammenhängende Aktivitäten nützlich:

Erstellung

Schreiben Sie PlantUML-, Mermaid-, Graphviz- oder anderen unterstützten Diagrammcode ein oder fügen Sie ihn ein.

Darstellung

Sehen Sie sich eine Live-Vorschau des Diagramms an, während Sie den Quellcode bearbeiten.

KI-unterstützte Verfeinerung

Fordern Sie die KI auf:

• Ein Diagramm aus einer Beschreibung erstellen

• Komponenten hinzufügen oder entfernen

• Knoten umbenennen

• Diagrammausrichtung ändern

• Verwandte Dienste gruppieren

• Systemgrenzen hinzufügen

• Ein überladenes Diagramm vereinfachen

• Eine Diagrammsyntax in eine andere konvertieren

• Syntaxprobleme beheben

• Sichtbare Beschriftungen übersetzen

Laut der Plattformdokumentation unterstützt VPasCode auch die automatische Formaterkennung, wenn Diagrammcode in den Editor eingefügt wird.

4. Auswahl der richtigen Diagrammsprache

PlantUML, Mermaid und Graphviz überschneiden sich in einigen Bereichen, sind jedoch für unterschiedliche Anwendungsfälle optimiert.

VPasCode listet die Unterstützung von PlantUML für UML, C4, Netzwerke, ERD und verwandte Diagrammtypen auf; Mermaid-Unterstützung für Flussdiagramme, Sequenzdiagramme, Klassendiagramme, Zustandsdiagramme, Gantt-Diagramme, Zeitpläne und mehr; sowie Graphviz-Unterstützung für gerichtete Graphen, Standardgraphen, Organigramme, Cluster und Datenflussdiagramme.

Praktische Auswahlregeln

Verwenden Sie Mermaid wenn:

• Das Diagramm befindet sich in der Markdown-Dokumentation.

• Sie benötigen ein schnelles Flussdiagramm oder Sequenzdiagramm.

• Ihre Zielgruppe umfasst Entwickler, die einen einfachen Syntax bevorzugen.

• Sie möchten ein Diagramm in einer Dokumentationsseite einbetten.

Verwenden Sie PlantUML wenn:

• Sie benötigen UML-Semantik.

• Sie modellieren Klassen, Komponenten, Bereitstellungen oder Interaktionen.

• Sie benötigen C4-Architekturdiagramme.

• Sie möchten mehr Kontrolle über UML-spezifische Konzepte.

Verwenden Sie Graphviz wenn:

• Das zentrale Konzept ist ein Graph von Beziehungen.

• Sie benötigen eine Abhängigkeitsanalyse.

• Sie visualisieren eine Hierarchie oder ein Netzwerk.

• Das automatische Layout ist wichtiger als die UML-Notation.

5. Erste Schritte mit VPasCode

Ein typischer Arbeitsablauf ist:

1. Öffnen Sie den VPasCode-Editor in einem Browser.

2. Wählen Sie eine Diagrammsprache aus oder fügen Sie vorhandenen Code ein.

3. Schreiben oder generieren Sie die Diagrammquelle.

4. Überprüfen Sie die Live-Vorschau.

5. Verwenden Sie KI, um die Quelle gegebenenfalls zu verfeinern.

6. Validieren Sie das Diagramm gegen das reale System.

7. Exportieren Sie das Ergebnis oder speichern Sie die Quelle in der Versionsverwaltung.

Der Kern-Editor, die Live-Rendering-Funktion und die Export-Funktionalität werden als in der kostenlosen VPasCode-Erfahrung verfügbar beschrieben, während einige erweiterte KI-Funktionen eine berechtigte Edition erfordern können.

Beginnen Sie mit einem klaren Diagrammziel

Bevor Sie die KI bitten, ein Diagramm zu erstellen, definieren Sie, was das Diagramm erklären soll.

Gute Ziele umfassen:

• Zeigen Sie, wie sich ein Benutzer anmeldet.

• Erklären Sie die Beziehung zwischen Diensten.

• Zeigen Sie die Bereitstellungstopologie.

• Beschreiben Sie einen Bestellgenehmigungsarbeitsablauf.

• Identifizieren Sie Abhängigkeiten zwischen Paketen.

• Kommunizieren Sie die Systemgrenze an die Beteiligten.

Vermeiden Sie Aufforderungen wie:

Erstellen Sie ein Diagramm der gesamten Unternehmensplattform.

Bevorzugen:

Erstellen Sie ein Systemkontextdiagramm, das Kunden, den Online-Shop, den Zahlungsanbieter und den Benachrichtigungsdienst zeigt. Schließen Sie keine internen Implementierungsdetails ein.

Ein Diagramm sollte im Allgemeinen eine Hauptfrage beantworten.

6. KI-Prompting zur Diagrammerstellung

KI-generierte Diagramme sind am nützlichsten, wenn der Prompt Folgendes angibt:

• Die Zielsprache

• Der Diagrammtyp

• Das zu modellierende System oder der Prozess

• Die Akteure oder Komponenten

• Beziehungen zwischen den Elementen

• Richtung des Flusses

• Gewünschter Detaillierungsgrad

• Zielgruppe

• Stil- oder Layout-Anforderungen

Allgemeine Prompt-Vorlage

Erstellen Sie ein [Diagrammtyp] unter Verwendung von [Mermaid/PlantUML/Graphviz].

Zweck:
[Welche Frage soll das Diagramm beantworten?]

Einschließen:
- [Element 1]
- [Element 2]
- [Element 3]

Beziehungen:
- [Beziehung 1]
- [Beziehung 2]

Einschränkungen:
- Halten Sie das Diagramm lesbar.
- Verwenden Sie kurze Beschriftungen.
- Gruppieren Sie zusammengehörige Komponenten.
- Erfinden Sie keine nicht spezifizierten Komponenten.
- Geben Sie nur gültigen [Sprache]-Code zurück.

Beispiel: Architektur-Prompt

Erstellen Sie ein Mermaid-Flussdiagramm für einen Online-Buchhandel.

Einschließen:
- Kundenbrowser
- Webanwendung
- API-Gateway
- Katalogdienst
- Bestelldienst
- Zahlungsanbieter
- PostgreSQL-Datenbank
- Benachrichtigungswarteschlange
- E-Mail-Dienst

Zeigen:
- Produktbrowsing
- Auftragseinreichung
- Zahlungsabwicklung
- Asynchrone Bestellbenachrichtigungen

Verwenden Sie ein Links-nach-Rechts-Layout. Gruppieren Sie Backend-Dienste in einem Subgraph. Halten Sie Beschriftungen prägnant.

Beispiel: UML-Prompt

Erstellen Sie ein PlantUML-Sequenzdiagramm für die Benutzeranmeldung.

Teilnehmer:
- Benutzer
- Browser
- Authentifizierungs-API
- Identitätsanbieter
- Benutzerdatenbank

Ablauf:
1. Benutzer übermittelt Zugangsdaten.
2. Browser sendet Zugangsdaten an die Authentifizierungs-API.
3. Authentifizierungs-API validiert diese mit dem Identitätsanbieter.
4. Der Identitätsanbieter liest Benutzerdaten.
5. Die API gibt ein Sitzungstoken zurück.
6. Der Browser zeigt die authentifizierte Startseite an.

Enthalten Sie einen alternativen Ablauf für ungültige Zugangsdaten.

Beispiel: Abhängigkeits-Prompt

Erstellen Sie ein Graphviz DOT-Abhängigkeitsdiagramm für diese Dienste:

- Frontend hängt von APIGateway ab.
- APIGateway hängt von UserService und OrderService ab.
- OrderService hängt von PaymentService und OrderDatabase ab.
- UserService hängt von UserDatabase ab.

Verwenden Sie ein Links-nach-Rechts-Layout und unterscheiden Sie Datenbanken visuell von Diensten.

7. Mermaid in VPasCode

Mermaid eignet sich hervorragend für leichte, dokumentationsfreundliche Diagramme. Seine Syntax ist kompakt und lesbar, was ihn zu einem guten Ausgangspunkt für KI-generierte Diagramme macht.

7.1 Mermaid-Flussdiagramm

flowchart LR
    User[Kunde] --> Browser[Web-Browser]
    Browser --> Gateway[API-Gateway]

    subgraph Backend
        Gateway --> Katalog[Katalogdienst]
        Gateway --> Bestellungen[Bestelldienst]
        Bestellungen --> Warteschlange[Nachrichtwarteschlange]
        Warteschlange --> Benachrichtigungen[Benachrichtigungsdienst]
    end

    Katalog --> KatalogDB[(Katalogdatenbank)]
    Bestellungen --> OrderDB[(Bestelldatenbank)]
    Benachrichtigungen --> Email[E-Mail-Anbieter]

Dieses Diagramm vermittelt:

• Benutzer-Einstiegspunkt

• Hauptanwendungsgrenze

• Backend-Dienste

• Datenspeicher

• Asynchrone Nachrichtenübermittlung

• Externe E-Mail-Integration

7.2 Mermaid-Sequenzdiagramm

sequenceDiagram
    actor Kunde
    participant Browser
    participant API as Bestell-API
    participant Payment as Zahlungsanbieter
    participant DB as Bestell-Datenbank
    participant Queue as Nachrichtenwarteschlange

    Kunde->>Browser: Bestellung einreichen
    Browser->>API: POST /orders
    API->>Payment: Zahlung autorisieren

    alt Zahlung genehmigt
        Payment-->>API: Autorisierung erfolgreich
        API->>DB: Bestellung speichern
        API->>Queue: OrderCreated veröffentlichen
        API-->>Browser: Bestellbestätigung zurückgeben
    else Zahlung abgelehnt
        Payment-->>API: Autorisierung fehlgeschlagen
        API-->>Browser: Zahlungsfehler zurückgeben
    end

Verwenden Sie Mermaid-Sequenzdiagramme, wenn die Reihenfolge der Nachrichten im Vordergrund steht und nicht die statische Struktur.

7.3 Mermaid-Zustandsdiagramm

stateDiagram-v2
    [*] --> Entwurf
    Entwurf --> Eingereicht: Bestellung einreichen
    Eingereicht --> ZahlungAusstehend: Zahlung starten
    ZahlungAusstehend --> Bezahlt: Zahlung genehmigt
    ZahlungAusstehend --> ZahlungFehlgeschlagen: Zahlung abgelehnt
    ZahlungFehlgeschlagen --> ZahlungAusstehend: Zahlung erneut versuchen
    Bezahlt --> Erfuellung: Erfuellung starten
    Erfuellung --> Versendet: Bestellung versenden
    Versendet --> Geliefert: Lieferung bestätigen
    Geliefert --> [*]

7.4 Mermaid-Entity-Relationship-Diagramm

erDiagram
    KUNDE ||--o{ BESTELLUNG : erstellt
    BESTELLUNG ||--|{ BESTELLPOSITION : enthält
    PRODUKT ||--o{ BESTELLPOSITION : erscheint_in
    BESTELLUNG ||--|| ZAHLUNG : hat

    KUNDE {
        int kunden_id
        string email
    }

    BESTELLUNG {
        int bestell_id
        date erstellungsdatum
        string status
    }

    PRODUKT {
        int produkt_id
        string name
        decimal preis
    }

    ZAHLUNG {
        int zahlung_id
        string anbieter
        string status
    }

Mermaid-Best-Practices

• Halten Sie Knotenbeschriftungen kurz.

• Verwenden Sie Subgraphen, um zusammengehörige Komponenten zu gruppieren.

• Vermeiden Sie es, jedes Implementierungsdetail in ein einziges Diagramm zu packen.

• Verwenden Sie eine konsistente Richtung wie LR oder TB.

• Teilen Sie große Diagramme nach Belangen auf.

• Verwenden Sie Sequenzdiagramme für Verhalten und Flussdiagramme für Struktur oder Entscheidungen.

• Verwenden Sie Kommentare, um ungewöhnliche Beziehungen dort zu dokumentieren, wo dies unterstützt wird.

8. PlantUML in VPasCode

PlantUML ist eine starke Wahl für formale Softwaremodellierung und UML-basierte Architekturdokumentation.

8.1 PlantUML-Komponentendiagramm

@startuml
titel Online-Shop - Komponentenarchitektur

actor Kunde

component "Webanwendung" as Web
component "API-Gateway" as Gateway
component "Katalogdienst" as Katalog
component "Bestelldienst" as Bestellungen
component "Zahlungsadapter" as Zahlung
database "Katalog-DB" as KatalogDB
database "Bestell-DB" as BestellDB

cloud "Externer Zahlungsanbieter" as Zahlungsanbieter

Kunde --> Web : Verwendet
Web --> Gateway : HTTPS
Gateway --> Katalog : Produkte durchsuchen
Gateway --> Bestellungen : Bestellung erstellen
Katalog --> KatalogDB : Produkte lesen
Bestellungen --> BestellDB : Bestellungen speichern
Bestellungen --> Zahlung : Zahlung abrechnen
Zahlung --> Zahlungsanbieter : Zahlung autorisieren

@enduml

PlantUML ist nützlich, wenn Sie Komponenten, Akteure, Datenbanken und explizite Beziehungen in einer UML-orientierten Notation benötigen.

8.2 PlantUML-Sequenzdiagramm

@startuml
titel Benutzeranmeldung

actor Benutzer
participant Browser
participant "Authentifizierungs-API" as API
participant "Identitätsanbieter" as IdP
database "Benutzerdatenbank" as DB

Benutzer -> Browser: Anmeldeinformationen eingeben
Browser -> API: Anmeldeinformationen einreichen
API -> IdP: Anmeldeinformationen validieren
IdP -> DB: Benutzerdatensatz laden
DB --> IdP: Benutzerdatensatz
IdP --> API: Validierungsergebnis

alt Anmeldeinformationen gültig
    API --> Browser: Sitzungstoken
    Browser --> Benutzer: Authentifizierte Startseite anzeigen
else Anmeldeinformationen ungültig
    API --> Browser: Authentifizierungsfehler
    Browser --> Benutzer: Fehlermeldung anzeigen
end

@enduml

Die Sequenzsyntax von PlantUML ist besonders geeignet zur Dokumentation von Anforderungslebenszyklen, Authentifizierung, Zahlungsworkflows und Dienstinteraktionen.

8.3 PlantUML C4-Systemkontextdiagramm

@startuml
!include <C4/C4_Kontext>

titel Online-Shop - Systemkontext

Person(Kunde, "Kunde", "Durchsucht Produkte und legt Bestellungen auf")
System(Shop, "Online-Shop", "Bietet Katalog, Kasse und Bestellverfolgung")
System_Ext(Zahlung, "Zahlungsanbieter", "Verarbeitet Kartenzahlungen")
System_Ext(E-Mail, "E-Mail-Dienst", "Sendet Bestellbenachrichtigungen")

Rel(Kunde, Shop, "Verwendet")
Rel(Shop, Zahlung, "Verarbeitet Zahlungen über")
Rel(Shop, E-Mail, "Sendet Benachrichtigungen über")

@enduml

C4-Diagramme sind nützlich, um Architektur auf verschiedenen Abstraktionsebenen zu kommunizieren:

• Systemkontext

• Container

• Komponente

• Code

Für die Kommunikation mit Führungskräften oder Stakeholdern beginnen Sie mit einem Systemkontext- oder Containerdiagramm anstelle eines detaillierten Klassendiagramms.

8.4 PlantUML-Klassendiagramm

@startuml
titel Bestellungs-Domänenmodell

class Kunde {
    +id: UUID
    +email: String
    +placeOrder()
}

class Bestellung {
    +id: UUID
    +status: Bestellstatus
    +total(): Geld
    +submit()
}

class Bestellposition {
    +quantity: int
    +unitPrice: Geld
}

class Produkt {
    +id: UUID
    +name: String
    +price: Geld
}

Kunde "1" --> "0..*" Bestellung : legt an
Bestellung "1" *-- "1..*" Bestellposition : enthält
Bestellposition "*" --> "1" Produkt : verweist auf

@enduml

PlantUML-Best-Practices

• Verwenden Sie C4 für die Architekturkommunikation.

• Verwenden Sie Komponentendiagramme für Service-Grenzen.

• Verwenden Sie Sequenzdiagramme für Laufzeit-Interaktionen.

• Verwenden Sie Klassendiagramme für Domänen- oder Code-Strukturen.

• Halten Sie Implementierungsdetails von hochstufigen Diagrammen fern.

• Verwenden Sie aussagekräftige Beziehungsbeschriftungen.

• Verwenden Sie Grenzen, um Eigentum und Systemumfang darzustellen.

• Vermeiden Sie es, jede Klasse, jeden Endpunkt und jede Datenbanktabelle in einem Diagramm darzustellen.

9. Graphviz in VPasCode

Graphviz verwendet die DOT-Sprache, um Knoten und Kanten zu beschreiben. Es ist besonders nützlich für Abhängigkeitsnetzwerke, gerichtete Graphen, Hierarchien und Topologiediagramme.

9.1 Graphviz-Abhängigkeitsgraph

digraph Abhängigkeiten {
    rankdir=LR;
    graph [fontname="Arial"];
    node [shape=box, style="rounded,filled", fillcolor="white"];
    edge [fontname="Arial"];

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

    OrderDatabase [
        shape=cylinder,
        fillcolor="lightblue",
        label="Bestelldatenbank"
    ];

    UserDatabase [
        shape=cylinder,
        fillcolor="lightblue",
        label="Benutzerdatenbank"
    ];
}

Diese Art von Graph kann helfen zu identifizieren:

• Häufig genutzte Dienste

• Lange Abhängigkeitsketten

• Zentrale Integrationspunkte

• Mögliche Kopplungsprobleme

• Datenbankeigentum

• Architektonische Engpässe

9.2 Graphviz-klastrierte Architektur

digraph Architektur {
    rankdir=LR;
    compound=true;

    subgraph cluster_clients {
        label="Clients";
        style=filled;
        color=lightgrey;

        WebBrowser [label="Webbrowser"];
        MobileApp [label="Mobile App"];
    }

    subgraph cluster_backend {
        label="Backend";
        style=filled;
        color=lightyellow;

        Gateway [label="API-Gateway"];
        Orders [label="Bestelldienst"];
        Users [label="Benutzerdienst"];
    }

    subgraph cluster_data {
        label="Daten";
        style=filled;
        color=lightblue;

        OrderDB [label="Bestelldatenbank", shape=cylinder];
        UserDB [label="Benutzerdatenbank", shape=cylinder];
    }

    WebBrowser -> Gateway;
    MobileApp -> Gateway;
    Gateway -> Orders;
    Gateway -> Users;
    Orders -> OrderDB;
    Users -> UserDB;
}

9.3 Graphviz-Hierarchie

digraph Organisation {
    rankdir=TB;
    node [shape=box];

    CEO -> CTO;
    CEO -> CFO;

    CTO -> Engineering;
    CTO -> Product;

    Engineering -> Platform;
    Engineering -> Applications;

    CFO -> Finance;
    CFO -> Procurement;
}

Graphviz-Best-Practices

• Verwenden Sie rankdir=LR für Abhängigkeitsflüsse.

• Verwenden Sie rankdir=TB für Hierarchien.

• Verwenden Sie Cluster, um Grenzen anzuzeigen.

• Verwenden Sie unterschiedliche Knotenformen für Dienste, Datenbanken und externe Systeme.

• Halten Sie Kantenebeschriftungen kurz.

• Vermeiden Sie übermäßiges Styling, bevor die Struktur korrekt ist.

• Verwenden Sie Graphviz, wenn Beziehungen wichtiger sind als formale UML-Semantik.

10. KI-gestützte Diagrammmodifikation

Das Erstellen des ersten Diagramms ist nur der Anfang. Der produktivste Arbeitsablauf ist eine iterative Verfeinerung.

Beginnen Sie mit einem einfachen Modell:

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

Fordern Sie dann gezielte Änderungen an:

Fügen Sie einen Cache zwischen der API und der Datenbank hinzu. Verwenden Sie eine Zylinderform für die Datenbank und eine eindeutige Farbe für den Cache.

Gruppieren Sie die API und die Datenbank innerhalb eines Backend-Subgraphen.

Fügen Sie eine asynchrone Nachrichtenwarteschlange zwischen der API und dem Benachrichtigungsdienst hinzu.

Vereinfachen Sie dieses Diagramm für ein nichttechnisches Publikum. Entfernen Sie Implementierungsdetails.

Ändern Sie das Layout von oben-nach-unten nach links-nach-rechts.

Umbenennen von API zu Bestellmanagement-API und verwenden Sie an anderer Stelle prägnante Beschriftungen.

Fügen Sie Fehlerpfade für Datenbank- und Zahlungsfehler hinzu.

Gezielte Eingabeaufforderungen sind zuverlässiger als die wiederholte Aufforderung an die KI, das gesamte Diagramm neu zu gestalten.

Überprüfen Sie KI-generierte Änderungen

Überprüfen Sie vor der Annahme einer Änderung Folgendes:

• Hat die KI bestehende Beziehungen beibehalten?

• Hat es Komponenten eingeführt, die nicht existieren?

• Hat es Pfeile umgekehrt?

• Hat es synchrone und asynchrone Kommunikation verwechselt?

• Hat es die Bedeutung einer Beziehung geändert?

• Hat es eine Syntax verwendet, die vom ausgewählten Renderer unterstützt wird?

• Hat es das Diagramm schwerer lesbar gemacht?

• Hat es unnötigerweise sensible Implementierungsdetails offengelegt?

Wenn das Tool einen Code-Diff oder eine Vorschauvergleiche bietet, prüfen Sie die textlichen und visuellen Änderungen, bevor Sie diese abschließen. Die VPasCode-Dokumentation beschreibt KI-gestützte Änderungs- und überprüfungsorientierte Bearbeitungsfunktionen.

11. Konvertierung zwischen Mermaid, PlantUML und Graphviz

Verschiedene Diagrammsprachen sind nicht perfekt austauschbar. Eine Konvertierung sollte das konzeptionelle Modell erhalten, nicht unbedingt jedes visuelle Detail.

Beispiel für ein konzeptionelles Modell

Kunde → Webanwendung → Bestelldienst → Zahlungsanbieter
                                      ↓
                                Bestell-Datenbank

Mermaid-Darstellung

flowchart LR
    Kunde --> Web
    Web --> Bestellungen
    Bestellungen --> Zahlung
    Bestellungen --> OrderDB[(Bestell-Datenbank)]

PlantUML-Darstellung

@startuml
actor Kunde
component "Webanwendung" as Web
component "Bestelldienst" as Orders
cloud "Zahlungsanbieter" as Payment
database "Bestelldatenbank" as OrderDB

Kunde --> Web
Web --> Orders
Orders --> Payment
Orders --> OrderDB

@enduml

Graphviz-Darstellung

digraph OrderFlow {
    rankdir=LR;

    Kunde [shape=ellipse];
    Web [label="Webanwendung"];
    Orders [label="Bestelldienst"];
    Payment [label="Zahlungsanbieter", shape=cloud];
    OrderDB [label="Bestelldatenbank", shape=cylinder];

    Kunde -> Web;
    Web -> Orders;
    Orders -> Payment;
    Orders -> OrderDB;
}

Konvertierungsrichtlinien

Wenn Sie zwischen Formaten konvertieren, teilen Sie der KI explizit Folgendes mit:

• Welche Elemente unverändert bleiben müssen

• Ob Beziehungen gerichtet sind

• Welche Grenzen beibehalten werden sollen

• Ob das Ziel ein formales UML oder ein leichtgewichtiges Flussdiagramm sein soll

• Ob das Styling beibehalten oder neu gestaltet werden soll

• Ob die Ausgabe die Kompatibilität mit der Dokumentation priorisieren soll

Beispiel:

Konvertieren Sie dieses Mermaid-Flussdiagramm in PlantUML.

Beibehalten:
- Alle Knoten
- Alle gerichteten Beziehungen
- Die Backend-Grenze
- Die Unterscheidung zwischen Datenbanken und externen Anbietern

Verwenden Sie ein PlantUML-Komponentendiagramm. Fügen Sie keine neuen Komponenten hinzu.
Geben Sie nur gültigen PlantUML-Code zurück.

12. Entwurf von Diagrammen für verschiedene Zielgruppen

Das gleiche System kann mehrere Diagramme erfordern.

Führungskräfte

Zeigen Sie:

• Wichtige Geschäftssysteme

• Externe Partner

• Kunden- oder Benutzerinteraktionen

• Hochstufige Datenflüsse

Vermeiden Sie:

• Klassennamen

• Interne Bibliotheken

• Infrastrukturkonfiguration

• Detaillierte Datenbanktabellen

Empfohlenes Format: PlantUML C4-Kontext oder ein einfaches Mermaid-Flussdiagramm.

Zielgruppe: Ingenieure

Anzeigen:

• Dienste

• APIs

• Warteschlangen

• Datenbanken

• Abhängigkeiten

• Fehlerpfade

• Eigentumsgrenzen

Empfohlenes Format: PlantUML-Komponentendiagramme, Mermaid-Architekturdiagramme oder Graphviz-Abhängigkeitsgraphen.

Zielgruppe: Betrieb

Anzeigen:

• Bereitstellungsknoten

• Regionen

• Cluster

• Lastverteiler

• Datenbanken

• Überwachungs- und Sicherungssysteme

Empfohlenes Format: PlantUML-Bereitstellungsdiagramme oder Graphviz-Topologiediagramme.

Zielgruppe: Produkt und Prozess

Anzeigen:

• Benutzeraktionen

• Geschäftsentscheidungen

• Genehmigungsschritte

• Alternative Pfade

• Zustandsübergänge

Empfohlenes Format: Mermaid-Flussdiagramme, Zustandsdiagramme oder PlantUML-Aktivitätsdiagramme.

13. Versionskontrolle und Repository-Organisation

Da Diagrammquellen Text sind, können sie zusammen mit dem Anwendungscode gespeichert werden.

Eine praktische Struktur könnte wie folgt aussehen:

docs/
└── diagrams/
    ├── context/
    │   └── system-context.puml
    ├── architecture/
    │   ├── service-architecture.mmd
    │   └── deployment-topology.dot
    ├── workflows/
    │   └── order-processing.mmd
    └── domain/
        └── order-model.puml

Verwenden Sie aussagekräftige Dateinamen, die den Zweck des Diagramms beschreiben, nicht sein visuelles Aussehen.

Gut:

order-processing-sequence.puml
service-dependencies.dot
system-context.puml

Weniger nützlich:

diagram-final-v2.puml
architecture-new.mmd
test-diagram.dot

Empfohlene Commit-Praxis

Halten Sie Diagrammänderungen nah an dem Code- oder Architekturänderung, die sie verursacht hat.

Beispiel-Commit:

Asynchronen Benachrichtigungsfluss zum Bestellarchitekturdiagramm hinzufügen

Vermeiden Sie es, wenn möglich, unzusammenhängende visuelle Bereinigungen mit strukturellen Änderungen zu vermischen. Kleinere Commits machen die Diagrammhistorie leichter verständlich.

14. CI/CD- und Dokumentations-Workflows

Ein ausgereifter Diagramm-as-Code-Workflow kann automatisierte Validierung und Darstellung umfassen.

Eine allgemeine Pipeline könnte wie folgt aussehen:

Pull-Request geöffnet
        ↓
Diagrammquelle geprüft
        ↓
Syntax dargestellt
        ↓
Generierte Ausgabe verglichen
        ↓
Dokumentationsvorschau erstellt
        ↓
Überprüfung genehmigt
        ↓
Diagramm veröffentlicht

Nützliche Prüfungen umfassen:

• Bestätigen, dass alle Diagrammdateien erfolgreich dargestellt werden.

• Syntaxfehler erkennen.

• SVG- oder PNG-Ausgaben generieren.

• Auf defekte Verweise prüfen.

• Generierte Diagramme mit vorherigen Versionen vergleichen.

• Diagramme auf Dokumentationsseiten veröffentlichen.

• Sicherstellen, dass Architekturdiagramme mit relevanten Codeänderungen aktualisiert werden.

Selbst wenn VPasCode für die Erstellung und Überprüfung verwendet wird, können Teams Quelldateien in ihrem bestehenden Dokumentations-Repository behalten und separate Automatisierung für die Batch-Darstellung verwenden.

Fragen zur Pull-Request-Überprüfung

Überprüfer sollten fragen:

• Spiegelt das Diagramm die aktuelle Implementierung wider?

• Ist der Umfang klar?

• Sind externe Systeme von internen Systemen unterschieden?

• Sind Pfeile klar beschriftet?

• Ist das Diagramm für sein Publikum zu detailliert?

• Fehlen Abhängigkeiten?

• Führt das Diagramm architektonische Annahmen ein?

• Ist die Quelle lesbar und wartbar?

15. Qualitätscheckliste

Verwenden Sie diese Checkliste vor der Veröffentlichung eines Diagramms.

Semantische Qualität

• Beantwortet das Diagramm eine klare Frage?

• Sind alle wichtigen Entitäten vorhanden?

• Sind die Beziehungen korrekt?

• Sind Richtung und Reihenfolge korrekt?

• Sind externe Systeme klar identifiziert?

• Sind Eigentumsgrenzen sichtbar?

Visuelle Qualität

• Ist das Layout leicht zu verfolgen?

• Sind Beschriftungen kurz und lesbar?

• Sind verwandte Elemente gruppiert?

• Sind sich kreuzende Linien minimiert?

• Ist das Diagramm ohne mündliche Erklärung verständlich?

• Ist der Detaillierungsgrad für das Publikum angemessen?

Quellenqualität

• Ist der Diagrammcode konsistent formatiert?

• Sind Namen aussagekräftig?

• Werden Kommentare dort verwendet, wo sie notwendig sind?

• Ist die gewählte Sprache angemessen?

• Kann ein anderes Teammitglied die Quelle ändern?

• Wird der Code ohne Fehler gerendert?

KI-Qualität

• Hat die KI irgendwelche Komponenten erfunden?

• Hat sie die beabsichtigte Bedeutung verändert?

• Hat sie nicht unterstützte Syntax eingeführt?

• Hat sie das bestehende Modell während der Änderung beibehalten?

• Wurden alle von der KI generierten Änderungen von einem Fachexperten überprüft?

16. Häufige Probleme und Lösungen

Das Diagramm ist zu überladen

Fragen Sie die KI:

Vereinfachen Sie dieses Diagramm für eine Systemarchitektur-Überprüfung. Behalten Sie nur Benutzer, Hauptdienste, Datenbanken, externe Anbieter und primäre Datenflüsse bei. Entfernen Sie Implementierungsdetails und sekundäre Abhängigkeiten.

Sie können ein Diagramm auch aufteilen in:

• Systemkontext

• Containerarchitektur

• Laufzeitsequenz

• Bereitstellungstopologie

• Abhängigkeitsgraph

Die KI erstellt falsche Beziehungen

Verwenden Sie explizite Anweisungen für Beziehungen:

Leiten Sie Beziehungen nicht ab. Verwenden Sie nur die unten aufgeführten Beziehungen. Wenn eine Beziehung nicht angegeben ist, lassen Sie sie weg.

Für komplexe Systeme stellen Sie eine strukturierte Liste bereit:

Beziehungen:
- WebApp ruft APIGateway über HTTPS auf.
- APIGateway ruft OrderService synchron auf.
- OrderService veröffentlicht OrderCreated an MessageQueue.
- NotificationService konsumiert OrderCreated asynchron.

Die Syntax wird nicht gerendert

Fragen Sie die KI, um den genauen Fehler zu diagnostizieren:

Korrigieren Sie diesen PlantUML-Syntaxfehler. Bewahren Sie die Diagrammstruktur bei und geben Sie nur den korrigierten Code zurück. Erklären Sie die Korrektur nach dem Code.

Überprüfen Sie anschließend, ob die vorgeschlagene Syntax vom ausgewählten Engine unterstützt wird.

Das generierte Diagramm sieht attraktiv aus, ist aber ungenau

Behandeln Sie visuelle Qualität und semantische Qualität getrennt. Ein poliertes Diagramm kann immer noch falsche Architekturen enthalten.

Validieren Sie jedes:

• Komponente

• Beziehung

• Richtung

• Grenze

• Datenspeicher

• Externe Abhängigkeit

• Fehlerpfad

Das Diagramm ändert sich während der KI-Bearbeitung zu stark

Verwenden Sie engere Änderungsanweisungen:

Nehmen Sie nur eine Änderung vor: Fügen Sie eine Nachrichtenwarteschlange zwischen OrderService und NotificationService hinzu. Ändern Sie keine anderen Knoten, Beschriftungen, Beziehungen oder Stile.

17. Empfohlener End-to-End-Arbeitsablauf

Schritt 1: Definieren Sie den Zweck

Schreiben Sie einen Satz:

Dieses Diagramm erklärt, wie eine Bestellung vom Checkout über die Zahlung bis zur Auslieferung verläuft.

Schritt 2: Wählen Sie die Engine

• Mermaid für einen Dokumentationsfluss

• PlantUML für eine formale Architektur oder ein UML-Modell

• Graphviz für Abhängigkeiten oder Netzwerkbeziehungen

Schritt 3: Erstellen Sie ein minimales Modell

Beginnen Sie mit den wichtigsten Akteuren, Komponenten und Beziehungen.

Schritt 4: Generieren oder schreiben Sie die erste Version

Verwenden Sie einen KI-Prompt mit expliziten Entitäten und Einschränkungen.

Schritt 5: Rendern Sie sofort

Verwenden Sie die Live-Vorschau, um Folgendes zu identifizieren:

• Fehlende Elemente

• Mehrdeutige Beschriftungen

• Schlechte Richtung

• Überfüllung

• Falsche Annahmen

Schritt 6: Verfeinern Sie in kleinen Schritten

Fordern Sie immer nur eine Änderung auf einmal an.

Schritt 7: Validieren Sie gegen die Realität

Vergleichen Sie das Diagramm mit:

• Quellcode

• API-Spezifikationen

• Infrastrukturdefinitionen

• Datenbankschemata

• Betriebsanleitungen

• Teamwissen

Schritt 8: Exportieren und veröffentlichen

Verwenden Sie SVG für skalierbare Dokumentation, PNG für schnelles Teilen und PDF für druckbare Materialien. VPasCode wirbt mit Exportoptionen, darunter PDF, SVG und PNG.

Schritt 9: Quelle speichern

Committen Sie den Diagrammcode in die Versionsverwaltung.

Schritt 10: Pflegen Sie es

Aktualisieren Sie das Diagramm, sobald sich die Architektur oder der Prozess ändert.

18. Wiederverwendbare KI-Prompt-Bibliothek

Erstellen Sie ein Mermaid-Flussdiagramm

Erstellen Sie ein Mermaid-Flussdiagramm für [Prozess/System].

Verwenden Sie ein Links-nach-Rechts-Layout.
Nur diese Elemente einbeziehen:
[list]

Diese Beziehungen verwenden:
[list]

Gruppieren Sie zusammengehörige Elemente in Subgraphen.
Verwenden Sie prägnante Beschriftungen.
Erfinden Sie keine zusätzlichen Komponenten.
Geben Sie nur gültigen Mermaid-Code zurück.

Erstellen Sie ein PlantUML-Komponentendiagramm

Erstellen Sie ein PlantUML-Komponentendiagramm für [System].

Interne Komponenten:
[list]

Externe Systeme:
[list]

Datenbanken:
[list]

Beziehungen:
[list]

Zeigen Sie Systemgrenzen an und beschriften Sie jede Beziehung.
Halten Sie das Diagramm für eine Architekturüberprüfung geeignet.
Geben Sie nur gültigen PlantUML-Code zurück.

Erstellen Sie ein Graphviz-Abhängigkeitsdiagramm

Erstellen Sie ein gerichtetes Graphviz DOT-Abhängigkeitsdiagramm.

Knoten:
[list]

Kanten:
[list]

Verwenden Sie ein Links-nach-Rechts-Layout.
Verwenden Sie Boxen für Dienste, Zylinder für Datenbanken und Wolken für externe Anbieter.
Gruppieren Sie Knoten bei Bedarf nach Subsystem.
Leiten Sie fehlende Abhängigkeiten nicht ab.
Geben Sie nur gültigen DOT-Code zurück.

Vereinfachen Sie ein Diagramm

Vereinfachen Sie dieses Diagramm für [Zielgruppe].

Erhalten Sie:
- [wichtige Elemente]
- [wichtige Beziehungen]

Entfernen Sie:
- [Implementierungsdetails]
- [sekundäre Abhängigkeiten]

Ändern Sie nicht die Bedeutung einer verbleibenden Beziehung.

Auf Richtigkeit prüfen

Prüfen Sie dieses Diagramm anhand der folgenden Architekturbeschreibung:

[Architekturbeschreibung]

Identifizieren Sie:
1. Fehlende Komponenten
2. Falsche Beziehungen
3. Falsche Richtung
4. Unklare Beschriftungen
5. Nicht gestützte Annahmen

Schreiben Sie das Diagramm noch nicht um.

Für Lesbarkeit refaktorisieren

Verbessern Sie die Lesbarkeit dieses Diagramms, ohne seine Bedeutung zu ändern.

Sie dürfen:
- Zusammengehörige Knoten gruppieren
- Das Layout neu ausrichten
- Beschriftungen verkürzen
- Grenzen hinzufügen
- Konsistente Stile verwenden

Sie dürfen nicht:
- Neue Komponenten hinzufügen
- Bestehende Beziehungen entfernen
- Die Richtung von Beziehungen ändern
- Domänenkonzepte umbenennen, ohne ihre Bedeutung zu bewahren

19. Abschließende Empfehlungen

Der effektivste VPasCode-Arbeitsablauf ist nicht „KI bitten, alles zu zeichnen”. Er ist:”

1. Definieren Sie das Kommunikationsziel.

2. Wählen Sie die Sprache, die zum Diagramm passt.

3. Erstellen Sie eine kleine erste Version.

4. Rendern Sie es sofort.

5. Verfeinern Sie es mit eng umrissenen KI-Anweisungen.

6. Überprüfen Sie das Modell auf technische Genauigkeit.

7. Speichern Sie die Quelle in der Versionsverwaltung.

8. Generieren Sie das Diagramm neu und veröffentlichen Sie es als Teil der Dokumentation.

Verwenden Sie Mermaid für zugängliche Dokumentationsdiagramme, PlantUML für formale UML- und Architekturmodellierung sowie Graphviz für Abhängigkeits- und Netzwerkanalysen. VPasCode vereint diese Ansätze in einem Editor, während KI die Syntax- und Iterationslast reduziert. Die letztendliche Verantwortung liegt jedoch beim Autor und den Architekturprüfern: KI kann die Diagrammerstellung beschleunigen, sollte jedoch nicht als autoritative Quelle der Systemwahrheit betrachtet werden.