VPasCode: KI-gestütztes Diagram-as-Code mit PlantUML

VPasCode ist ein browserbasierter Diagram-as-Code-Arbeitsbereich, der einen Texteditor, eine Live-Diagramm-Rendering-Funktion und PlantUML-Unterstützung sowie KI-gestützte Diagrammerstellung und -bearbeitung kombiniert. Anstatt Formen manuell auf eine Zeichenfläche zu ziehen, beschreiben Sie ein Diagramm mit PlantUML-Code—oder bitten Sie die KI, die erste Version zu erstellen—und verfeinern Sie dann den Quelltext, bis das gerenderte Diagramm Ihr Design klar vermittelt.

Dieser Workflow ist besonders nützlich für Softwarearchitektur, UML-Modellierung, technische Dokumentation, Systemdesign-Reviews und Diagramme, die sich gemeinsam mit dem Quellcode weiterentwickeln müssen.

1. Was ist Diagram-as-Code?

Diagram-as-Codestellt ein Diagramm als Text dar und nicht als statische Zeichendatei. Der Text fungiert als Quelle der Wahrheit, während eine Rendering-Engine ihn in ein visuelles Diagramm umwandelt.

Ein einfaches PlantUML-Sequenzdiagramm sieht so aus:

@startuml
actor User
participant Browser
participant API
database Database

User -> Browser: Login-Formular einreichen
Browser -> API: POST /login
API -> Database: Anmeldeinformationen validieren
Database --> API: Benutzerdatensatz
API --> Browser: Sitzungstoken
Browser --> User: Dashboard anzeigen
@enduml

Der Code kann:

• in Git gespeichert werden

• in Pull-Requests überprüft werden

• mit gewöhnlichen Texteditoren aktualisiert werden

• als Vorlage wiederverwendet werden

• in SVG, PNG oder PDF gerendert werden

• in technische Dokumentation eingebettet werden

• von der KI modifiziert werden, wobei eine menschliche Überprüfung beibehalten wird

Traditionelle Diagramme veralten oft, weil die Aktualisierung einer visuellen Zeichenfläche Zeit in Anspruch nimmt. Mit Diagram-as-Code können das Hinzufügen eines Dienstes, das Ändern einer Beziehung oder das Umbenennen einer Komponente als Textänderung behandelt werden. Dies reduziert den Wartungsaufwand, obwohl das Diagramm dennoch auf Richtigkeit überprüft werden muss.

2. Was VPasCode bietet

VPasCodebringt mehrere Diagrammsprachen und Visualisierungsformate in einen einzigen browserbasierten Arbeitsbereich. Die dokumentierten Funktionen umfassen PlantUML, Mermaid, D2, Graphviz, Markmap, Datenformate und andere textbasierte Eingaben. Es bietet zudem eine automatische Formaterkennung, sodass eingefügter Diagrammcode erkannt und gerendert werden kann, ohne dass die Sprache manuell ausgewählt werden muss.

Die für PlantUML-Nutzer wichtigsten Funktionen sind:

• PlantUML-Bearbeitung: Schreiben und bearbeiten Sie PlantUML-Skripts in einem Code-Editor.

• Live-Vorschau: Sehen Sie das gerenderte Diagramm während der Bearbeitung.

• KI-Generierung: Beschreiben Sie ein Diagramm in natürlicher Sprache und generieren Sie PlantUML-Code.

• KI-Modifikation: Fordern Sie die KI auf, Teile eines bestehenden Diagramms hinzuzufügen, zu entfernen, neu zu organisieren oder zu vereinfachen.

• KI-Fehlerbehebung: Fordern Sie Hilfe zur Korrektur ungültiger oder fehlerhafter Syntax an.

• KI-Übersetzung: Übersetzen Sie Diagrammbeschriftungen für mehrsprachige Teams.

• Export: Laden Sie Diagramme in Formaten wie SVG, PNG und PDF herunter.

• Freigabe: Erstellen Sie teilbare Links für Diagramme.

• Mehrere Diagramm-Engines: Wechseln Sie bei Bedarf zwischen PlantUML und anderen Diagramm-as-Code-Standards.

Die Kernfunktionen des Editors und der Darstellung werden als kostenlos beschrieben, während einige KI-Diagnosefunktionen und cloudbasierte Funktionen von einem kostenpflichtigen Visual Paradigm-Plan oder Add-on abhängen können. Die aktuelle Lizenzierung sollte in der VPasCode-Schnittstelle überprüft werden, da sich die Details der Pläne ändern können.

3. Warum PlantUML in VPasCode verwenden?

PlantUML ist eine starke Wahl, wenn Sie formale Software-Ingenieur-Diagramme benötigen. Es unterstützt viele Diagrammtypen, darunter:

• Sequenzdiagramme

• Klassendiagramme

• Anwendungsfalldiagramme

• Aktivitätsdiagramme

• Zustandsdiagramme

• Komponentendiagramme

• Bereitstellungsdiagramme

• Objektdiagramme

• Zeitdiagramme

• Entity-Relationship-Diagramme

• Netzwerkdiagramme

• Gantt-Diagramme

• Mindmaps und andere spezialisierte Visualisierungen

PlantUML ist besonders nützlich, wenn das Diagramm Beziehungen, Interaktionen, Abhängigkeiten oder Architekturen ausdrücken soll und nicht nur einen Prozess veranschaulichen soll.

Eine praktische Aufteilung der Verantwortlichkeiten ist:

VPasCode ist nützlich, wenn ein Team mit mehr als einem dieser Formate arbeitet und eine gemeinsame Bearbeitungs- und Vorschauumgebung wünscht.

4. Erste Schritte mit VPasCode

Da VPasCode im Browser ausgeführt wird, ist in der Regel keine lokale Installation oder Einrichtung zur Diagramm-Rendering erforderlich. Öffnen Sie den VPasCode-Editor, erstellen Sie ein Diagrammskript oder fügen Sie eines ein, und verwenden Sie die Live-Vorschau, um das Ergebnis zu überprüfen.

Ein grundlegender Arbeitsablauf ist:

1. Öffnen Sie den VPasCode-Editor.

   

2. Erstellen Sie ein neues Diagramm oder fügen Sie vorhandenen PlantUML-Code ein.

3. Lassen Sie den Editor das PlantUML-Format erkennen oder wählen Sie PlantUML bei Bedarf explizit aus.

4. Überprüfen Sie die live gerenderte Vorschau.

   

5. Korrigieren Sie Syntax- oder Layout-Probleme.

6. Verwenden Sie KI, um Code zu generieren oder zu modifizieren, wenn dies hilfreich ist.

7. Exportieren oder teilen Sie das fertige Diagramm.

8. Speichern Sie die PlantUML-Quelle in Ihrem Projekt-Repository, wenn das Diagramm Teil einer laufenden Dokumentation ist.

Die wichtigste Gewohnheit ist, den Quellcode zu erhalten. Das exportierte Bild ist ein Ausgabeergebnis; das PlantUML-Skript ist das wartbare Artefakt.

5. Erstellen eines PlantUML-Diagramms manuell

Beginnen Sie mit den Standard-Grenzen von PlantUML:

@startuml
' Diagramminhalt geht hier hin
@enduml

Kommentare beginnen mit einem einzelnen Apostroph:

@startuml
' Dies ist ein Kommentar
Alice -> Bob: Hallo
@enduml

Ein minimales Sequenzdiagramm:

@startuml
Alice -> Bob: Anfrage
Bob --> Alice: Antwort
@enduml

Der Pfeil bestimmt die Richtung und den visuellen Stil der Interaktion. Häufige Beispiele sind:

A -> B: Synchroner Auftrag
A --> B: Gestrichelte Antwort
A ->> B: Asynchrones Nachrichten
A <-- B: Nachricht in umgekehrter Richtung
A -[#red]> B: Farbige Beziehung

Teilnehmer können explizit deklariert werden:

@startuml
actor Kunde
participant WebApp
participant PaymentService
database Bestellungen

Kunde -> WebApp: Bestellung aufgeben
WebApp -> PaymentService: Zahlung autorisieren
PaymentService -> Bestellungen: Bestellung speichern
Bestellungen --> PaymentService: Bestell-ID
PaymentService --> WebApp: Zahlung genehmigt
WebApp --> Kunde: Bestätigung
@enduml

Explizite Deklarationen verbessern die Lesbarkeit und erleichtern die Steuerung von Aliasen, Typen und dem visuellen Erscheinungsbild.

6. KI bitten, PlantUML zu generieren

Die Qualität eines von einer KI generierten Diagramms hängt stark vom Prompt ab. Eine vage Anfrage wie „Erstellen Sie ein Architekturdiagramm“ kann ein attraktives, aber unvollständiges Ergebnis liefern. Ein guter Prompt gibt Folgendes an:

• Der Diagrammtyp

• Die Systemgrenze

• Die Akteure oder Komponenten

• Die wichtigen Beziehungen

• Die Kommunikationsrichtung

• Der Detaillierungsgrad

• Einschränkungen bei der Notation

• Das gewünschte Ausgabeformat

Zum Beispiel:

Erstellen Sie ein PlantUML-Sequenzdiagramm für die Anmeldung eines Kunden in einer Webanwendung mit OAuth 2.0. Beziehen Sie den Kunden, den Browser, den Anwendungsserver, den Identitätsanbieter, den Autorisierungsserver und die Benutzerdatenbank ein. Zeigen Sie den Autorisierungscode-Fluss, den Token-Austausch, die Benutzersuche, die Erfolgsantwort und eine Alternative bei fehlgeschlagenem Login. Halten Sie das Diagramm lesbar und verwenden Sie die PlantUML-Sequenzsyntax.

Ein nützlicher Architektur-Prompt könnte lauten:

Erstellen Sie ein PlantUML-Komponentendiagramm für einen Online-Shop. Beziehen Sie Folgendes ein:
- Webbrowser
- CDN
- Web-Frontend
- API-Gateway
- Produktdienst
- Bestelldienst
- Zahlungsanbieter
- PostgreSQL-Datenbank
- Redis-Cache
- Nachrichtenbroker

Gruppieren Sie die Komponenten nach Web, Anwendung, externe Systeme und Daten. Zeigen Sie den Hauptanforderungsweg zum Durchsuchen von Produkten und zum Aufgeben einer Bestellung. Schließen Sie Infrastrukturdetails aus, die für den Geschäftsablauf nicht relevant sind.

Die KI-Funktionen von VPasCode sind darauf ausgelegt, Diagrammcode aus natürlichen Sprachbeschreibungen zu generieren und das Ergebnis im ausgewählten Format darzustellen. Der generierte Code sollte als erster Entwurf behandelt werden: Überprüfen Sie die Beziehungen, Annahmen, Beschriftungen und Auslassungen, bevor Sie ihn als Dokumentation verwenden.

7. Beispiel: KI-generiertes Sequenzdiagramm

Ein verfeinertes Ergebnis für die OAuth-Anmeldeanfrage könnte so aussehen:

@startuml
Titel OAuth 2.0-Anmeldeablauf

Akteur Benutzer
Teilnehmer Browser
Teilnehmer "Anwendungsserver" als App
Teilnehmer "Identitätsanbieter" als IdP
Datenbank "Benutzerdatenbank" als DB

Benutzer -> Browser: Auf "Anmelden" klicken
Browser -> App: Anmeldung anfordern
App --> Browser: Weiterleitung zu IdP
Browser -> IdP: Autorisierungsanfrage
Benutzer -> IdP: Authentifizieren und autorisieren
IdP --> Browser: Autorisierungscode
Browser -> App: Autorisierungscode zurückgeben
App -> IdP: Code gegen Tokens tauschen
IdP --> App: Zugriffstoken und ID-Token
App -> DB: Benutzer finden oder erstellen
DB --> App: Benutzerprofil
App --> Browser: Anwendungssitzung erstellen
Browser --> Benutzer: Authentifiziertes Dashboard anzeigen

alt Authentifizierung schlägt fehl
    IdP --> Browser: Authentifizierungsfehler
    Browser --> Benutzer: Login-Fehler anzeigen
end
@enduml

Die KI kann ein technisch gültiges Diagramm erzeugen, das die tatsächliche Implementierung dennoch verzerrt darstellt. Beispielsweise könnte sie zeigen, wie der Browser direkt mit einer Datenbank kommuniziert, oder die Token-Validierung auslassen. Validieren Sie das Ergebnis anhand des realen Systems.

8. Bearbeiten eines bestehenden Diagramms mit KI

KI ist oft nützlicher für kontrollierte Änderungen als für die Erstellung eines gesamten Diagramms von Grund auf.

Beispiele für gezielte Anweisungen sind:

Fügen Sie einen Redis-Cache zwischen dem API-Gateway und dem Produktdienst hinzu. Zeigen Sie einen Cache-Hit und einen Cache-Miss-Pfad.

Gruppieren Sie alle Datenbankkomponenten in einem Paket der Datenschicht.

Entfernen Sie Implementierungsdetails und lassen Sie nur die wichtigsten Geschäftsdienste.

Fügen Sie einen alternativen Pfad für Zahlungsfehler und Stornierungen von Bestellungen hinzu.

Ändern Sie den Namen von "Auth Service" überall in "Identity Service", ohne andere Beziehungen zu ändern.

Konvertieren Sie dieses Sequenzdiagramm in ein Komponentendiagramm, das Verantwortlichkeiten statt Nachrichten-aus-Nachrichten-Interaktionen zeigt.

VPasCode beschreibt die KI-gestützte Diagrammänderung als eine Möglichkeit, bestehende Skripte mit Befehlen in natürlicher Sprache zu aktualisieren. Einige Workflows können auch einen visuellen oder zeilenweisen Vergleich anbieten, bevor Änderungen akzeptiert werden.

Ein sicherer Änderungs-Workflow ist:

1. Behalten Sie den ursprünglichen Quellcode unverändert.

2. Fordern Sie von der KI eine fokussierte Änderung an.

3. Überprüfen Sie die vorgeschlagenen Code-Änderungen.

4. Rendern Sie das Ergebnis.

5. Stellen Sie sicher, dass unverwandte Beziehungen nicht verändert wurden.

6. Akzeptieren Sie die Änderung erst nach visueller und semantischer Prüfung.

7. Committen Sie den aktualisierten Quellcode mit einer aussagekräftigen Nachricht.

9. Einsatz von KI zur Behebung von PlantUML-Fehlern

PlantUML-Fehler entstehen häufig durch:

• Fehlendes@enduml

• Falsch geschriebene Schlüsselwörter

• Ungültige Teilnehmerdeklarationen

• Ungleichgewichtige Gruppierungsblöcke

• Falsche Klammern oder runde Klammern

• Nicht unterstützte Syntax, die von einer anderen Diagrammsprache kopiert wurde

• Falsch escapeierte Sonderzeichen

• Mischung aus Mermaid-, PlantUML- und Graphviz-Syntax

Beispielsweise enthält dieses Skript eine fehlerhafte Deklaration:

@startuml
participant Browser
particpant API
Browser -> API: Request
@enduml

Die Korrektur lautet:

@startuml
participant Browser
participant API
Browser -> API: Request
@enduml

Wenn Sie eine KI-Reparaturfunktion verwenden, geben Sie das beabsichtigte Verhalten sowie den fehlerhaften Code an. Dies hilft, eine syntaktische Korrektur zu vermeiden, die die Bedeutung des Diagramms verändert:

Korrigieren Sie den PlantUML-Syntaxfehler, bewahren Sie jedoch die Teilnehmer, die Nachrichtenreihenfolge und die Beschriftungen bei. Erklären Sie, welche Zeile ungültig war.

VPasCode dokumentiert KI-gestützte Syntaxkorrekturen für fehlerhafte Diagrammskripte. Solche Korrekturen sollten dennoch überprüft werden, insbesondere wenn die KI mehr als eine Zeile ändert.

10. Kernmuster von PlantUML

10.1 Sequenzdiagramme

Sequenzdiagramme zeigen Interaktionen über die Zeit.

@startuml
actor Kunde
participant Schaufenster
participant Auftragsdienst
database AuftragsDB

Kunde -> Schaufenster: Auftrag einreichen
Schaufenster -> Auftragsdienst: Auftrag erstellen
Auftragsdienst -> AuftragsDB: Auftrag einfügen
AuftragsDB --> Auftragsdienst: Auftrag erstellt
Auftragsdienst -> Schaufenster: Auftragsbestätigung
Schaufenster -> Kunde: Bestätigung anzeigen
@enduml

Verwenden Sie alt, opt, loop, und par zur Darstellung des Kontrollflusses:

@startuml
participant Kunde
participant API

Kunde -> API: Anfrage einreichen

alt Anfrage ist gültig
    API --> Kunde: 200 OK
else Anfrage ist ungültig
    API --> Kunde: 400 Bad Request
end

loop Wiederholung bis zu dreimal
    Kunde -> API: Anfrage wiederholen
end
@enduml

10.2 Klassendiagramme

Klassendiagramme drücken Struktur, Attribute, Methoden und Beziehungen aus.

@startuml
class Kunde {
  -id: UUID
  -email: String
  +placeOrder(): Order
}

class Order {
  -id: UUID
  -status: OrderStatus
  +calculateTotal(): Money
}

class OrderItem {
  -quantity: int
  -unitPrice: Money
}

Kunde "1" --> "0..*" Order : legt fest
Order "1" *-- "1..*" OrderItem : enthält
@enduml

Häufig verwendete Beziehungssymbole umfassen:

A -- B       ' Assoziation
A o-- B     ' Aggregation
A *-- B     ' Komposition
A ..> B     ' Abhängigkeit
A --|> B    ' Vererbung
A ..|> B    ' Realisierung

10.3 Komponentendiagramme

Komponentendiagramme sind für die Softwarearchitektur auf hoher Ebene effektiv.

@startuml
titel Online-Store-Komponenten

package "Client-Schicht" {
  [Web-Browser]
  [Mobile-App]
}

package "Anwendungsschicht" {
  [API-Gateway]
  [Katalog-Service]
  [Bestell-Service]
  [Zahlungs-Service]
}

package "Datenschicht" {
  database "Katalog-DB" as KatalogDB
  database "Bestell-DB" as OrderDB
}

cloud "Externer Zahlungsanbieter" as PaymentProvider

[Web-Browser] --> [API-Gateway]
[Mobile-App] --> [API-Gateway]
[API-Gateway] --> [Katalog-Service]
[API-Gateway] --> [Bestell-Service]
[Katalog-Service] --> KatalogDB
[Bestell-Service] --> OrderDB
[Zahlungs-Service] --> PaymentProvider
[Bestell-Service] --> [Zahlungs-Service]
@enduml

10.4 Aktivitätsdiagramme

Aktivitätsdiagramme zeigen Arbeitsabläufe und Verzweigungslogik.

@startuml
start

:Bestellung empfangen;
:Bestellung validieren;

if (Bestellung gültig?) then (ja)
  :Lagerbestand reservieren;
  if (Lagerbestand verfügbar?) then (ja)
    :Zahlung autorisieren;
  :Versand erstellen;
  else (nein)
    :Kunde benachrichtigen;
  endif
else (nein)
  :Bestellung ablehnen;
endif

stop
@enduml

10.5 Use-Case-Diagramme

Use-Case-Diagramme identifizieren Akteure und Systemfähigkeiten.

@startuml
von links nach rechts

actor Kunde
actor Administrator

rectangle "Online-Store" {
  usecase "Produkte durchsuchen" as Browse
  usecase "Bestellung aufgeben" as Place
  usecase "Versand verfolgen" as Track
  usecase "Katalog verwalten" as Manage
}

Kunde --> Browse
Kunde --> Place
Kunde --> Track
Administrator --> Manage
@enduml

11. Verbesserung von Layout und Lesbarkeit

KI kann gültigen Code generieren, der ein schwer lesbares Diagramm erzeugt. Die Layout-Qualität ist Teil der Diagramm-Qualität.

Nützliche PlantUML-Techniken umfassen:

von links nach rechts

Dies ändert die allgemeine Ausrichtung vieler Diagramme.

Verwenden Sie Pakete oder Rechtecke, um Grenzen festzulegen:

package "Auftragsverwaltung" {
  [Order API]
  [Order Worker]
}

Verwenden Sie Aliasnamen, um lange Bezeichnungen lesbar zu halten:

component "Kundenbenachrichtigungsdienst" as Notification

Verwenden Sie bei Bedarf Zeilenumbrüche in Beschriftungen:

[Zahlungsdienstn(PCI-Grenze)] as Payment

Verwenden Sie Notizen zur Klärung des Kontexts:

note right of Payment
  Verwaltet die Zahlungsautorisierung.
  Kartendaten werden nicht lokal gespeichert.
end note

Verwenden Sie Farben sparsam:

skinparam component {
  BackgroundColor<<critical>> #FFCCCC
  BorderColor<<critical>> #990000
}

[Payment Service] <<critical>>

Eine nützliche Regel ist, die Verständlichkeit gegenüber der Dekoration zu optimieren. Wenn ein Diagramm viele Farben, Farbverläufe oder dekorative Elemente benötigt, um verständlich zu bleiben, enthält es möglicherweise zu viele Informationen.

12. Prompting für bessere Diagramme

Ein starker KI-Prompt besteht normalerweise aus fünf Teilen:

1. Rolle oder Kontext
   “Sie dokumentieren eine Microservice-Architektur…”

2. Diagrammtyp
   “Erstellen Sie ein PlantUML-Komponentendiagramm…”

3. Entitäten
   „Browser, API-Gateway, Bestelldienst, Zahlungsdienst usw. einbeziehen…“

4. Beziehungen und Verhalten
   „Synchrone Aufrufe, asynchrone Ereignisse und Datenbankbesitz darstellen…“

5. Ausgabebedingungen
   „Gültige PlantUML-Syntax verwenden, Komponenten nach Grenzen gruppieren, Implementierungsdetails vermeiden und Beschriftungen knapp halten.“

Beispiel:

Sie dokumentieren eine produktive E-Commerce-Plattform.

Erstellen Sie ein PlantUML-Komponentendiagramm. Einbeziehen:
- Kundenbrowser
- CDN
- Frontend
- API-Gateway
- Katalogdienst
- Bestelldienst
- Zahlungsdienst
- Benachrichtigungsdienst
- PostgreSQL
- Redis
- Kafka
- Externer Zahlungsanbieter

Darstellen:
- Browserverkehr durch das CDN und Frontend
- API-Gateway-Routing
- Katalog-Lesezugriffe aus Redis und PostgreSQL
- Bestelldaten, die an Kafka veröffentlicht werden
- Zahlungsautorisierung über den externen Anbieter
- Benachrichtigungen, die Bestelldaten konsumieren

Gruppieren Sie Komponenten in Client, Anwendung, Messaging, Daten und externe Systeme. Verwenden Sie knappe Beschriftungen und vermeiden Sie die Darstellung einzelner Klassen oder HTTP-Endpunkte.

Für Änderungen den Umfang einschränken:

Ändern Sie nur den bestellverarbeitenden Teil dieses PlantUML-Diagramms. Fügen Sie einen Betrugsprüfungsdienst zwischen Bestelldienst und Zahlungsdienst hinzu. Bewahren Sie alle bestehenden Teilnehmer, Beschriftungen und nicht verwandten Beziehungen bei.

13. Überprüfung KI-generierter Diagramme

KI-generierte Diagramme müssen sowohl einer Syntaxprüfung als auch einer Domänenprüfung standhalten.

Syntaxprüfung

Überprüfen Sie Folgendes:

• Das Diagramm wird erfolgreich gerendert.

• Alle Blöcke sind geschlossen.

• Teilnehmer und Aliasnamen sind konsistent.

• Die Beziehungs-Syntax entspricht PlantUML.

• Es wurde keine Mermaid- oder Graphviz-Syntax gemischt.

• Sonderzeichen werden korrekt behandelt.

Semantische Prüfung

Überprüfen Sie Folgendes:

• Jede Hauptkomponente ist vorhanden.

• Beziehungen stellen das reale System dar.

• Richtungspfeile sind aussagekräftig.

• Datenspeicher werden nicht als Dienste dargestellt, es sei denn, dies ist beabsichtigt.

• Vertrauensgrenzen sind korrekt.

• Externe Systeme sind eindeutig gekennzeichnet.

• Fehlerpfade werden dort nicht weggelassen, wo sie relevant sind.

• Der Detaillierungsgrad entspricht dem Zielpublikum.

Kommunikationsüberprüfung

Stellen Sie sicher, dass:

• Das Diagramm hat einen Hauptzweck.

• Beschriftungen sind kurz und spezifisch.

• Die Leserrichtung ist eindeutig.

• Das Diagramm ist nicht überladen.

• Ähnliche Komponenten sind gruppiert.

• Der Titel erklärt, was dargestellt wird.

• Ein Leser, der mit der Implementierung nicht vertraut ist, kann es verstehen.

KI kann ein Diagramm erzeugen, das syntaktisch korrekt, aber architektonisch falsch ist. Betrachten Sie das erfolgreiche Rendern als Beginn der Überprüfung, nicht als Ende.

14. Versionsverwaltung von VPasCode-Diagrammen

Speichern Sie die PlantUML-Quelle zusammen mit der Dokumentation oder dem Anwendungscode:

docs/
├── architecture/
│   ├── system-context.puml
│   ├── container-view.puml
│   ├── login-sequence.puml
│   └── order-flow.puml
└── README.md

Eine nützliche Namenskonvention ist:

<Thema>-<Diagrammtyp>.puml

Beispiele:

authentication-sequence.puml
billing-component.puml
order-state.puml
deployment-diagram.puml

Ein quellenkontrollierter Workflow könnte sein:

1. Aktualisieren Sie die .pumlDatei.

2. Öffnen Sie sie oder fügen Sie sie in VPasCode ein.

3. Überprüfen Sie die Live-Darstellung.

4. Exportieren Sie bei Bedarf eine Vorschau.

5. Committen Sie die Quelländerung.

6. Aktualisieren Sie generierte Bilder oder Dokumentation nur bei Bedarf.

7. Überprüfen Sie Diagrammänderungen zusammen mit Code- oder Architekturänderungen.

Beispielhafte Commit-Nachrichten:

docs: OAuth-Login-Sequenzdiagramm hinzufügen
docs: Redis-Cache in der Katalogarchitektur anzeigen
docs: Diagramm der Bestellkomponente vereinfachen

Vermeiden Sie es, nur ein PNG oder SVG zu committen, wenn die Quelle erhalten werden kann. Bilder sind schwer zu vergleichen und zu bearbeiten; die PlantUML-Quelle ist durchsuchbar und überprüfbar.

15. Exportieren und Teilen von Diagrammen

Sobald das Diagramm abgeschlossen ist, unterstützt VPasCode das Exportieren gerendierter Diagramme in gängigen Formaten wie:

• SVG:Am besten geeignet für Dokumentation, Websites und skalierbare technische Diagramme.

• PNG:Praktisch für Präsentationen, Tickets, Chat und leichtgewichtiges Teilen.

• PDF:Nützlich für den Druck und formelle Dokumente.

VPasCode dokumentiert zudem teilbare URLs für Live-Diagramme, sodass andere das gerenderte Ergebnis ansehen können, ohne die Quelle manuell nachzubilden.

Verwenden Sie SVG, wenn:

• Text muss bei verschiedenen Größen scharf bleiben.

• Das Diagramm wird auf einer Webseite angezeigt.

• Sie möchten den Vektoroutput bearbeiten oder überprüfen.

Verwenden Sie PNG, wenn:

• Ein Tool unterstützt kein SVG.

• Sie benötigen eine einfache Bildanlage.

• Das Diagramm wird in eine Chat-Nachricht oder ein Issue-Tracker-System eingefügt.

Verwenden Sie PDF, wenn:

• Das Diagramm ist Teil einer druckbaren Spezifikation.

• Es wird als formelles Dokument verbreitet.

• Das Seitenlayout ist wichtig.

16. Übersetzen von PlantUML-Diagrammen

KI-Übersetzungen können nützlich sein, wenn Beschriftungen internationalen Teams präsentiert werden müssen. Übersetzen Sie jedoch Diagrammtexte und nicht die technische Syntax.

Beispielsweise übersetzen Sie Folgendes:

Kunde -> OrderService: Bestellung einreichen

in eine andere Sprache unter Beibehaltung von:

• Kunde

• OrderService

• Pfeilsyntax

• PlantUML-Schlüsselwörter

• Aliasnamen

• URLs

• API-Namen

• Produktbezeichnungen

• Abkürzungen

Ein Übersetzungsauftrag sollte eindeutig sein:

Übersetzen Sie nur sichtbare Beschriftungen und Nachrichtentexte ins Japanische. Ändern Sie keine PlantUML-Schlüsselwörter, Aliasnamen, Beziehungs-Syntax, API-Namen, Produktbezeichnungen oder Code-Bezeichner.

Überprüfen Sie Übersetzungen fachspezifischer Begriffe sorgfältig. Eine wörtliche Übersetzung kann grammatikalisch korrekt, aber technisch irreführend sein. VPasCode beschreibt KI-Übersetzung als eine Fähigkeit zur Übersetzung von Diagrammtexten und Beschriftungen über verschiedene Sprachen hinweg.

17. Häufige Probleme und Lösungen

Das Diagramm wird nicht gerendert

Überprüfen Sie:

• @startuml und @enduml

• Falsch geschriebene PlantUML-Schlüsselwörter

• Nicht geschlossenes alt, loop, package, oder rectangle Blöcke

• Ungültige Aliasnamen

• Sonderzeichen in Beschriftungen

• Ob der eingefügte Code tatsächlich PlantUML ist

Fragen Sie die KI:

Finden Sie den PlantUML-Syntaxfehler. Bewahren Sie die beabsichtigten Teilnehmer und die Nachrichtenreihenfolge bei. Geben Sie den korrigierten PlantUML-Code zurück und erklären Sie die Korrektur kurz.

Das Diagramm ist zu breit

Versuchen Sie:

• Verwenden von Richtung von links nach rechtsnur wenn es das Layout verbessert

• Aufteilen eines großen Diagramms in mehrere Ansichten

• Verkürzen von Teilnehmernamen mit Aliasen

• Gruppieren verwandter Komponenten

• Entfernen von Interaktionen mit geringem Wert

• Verschieben von erläuterndem Text in Notizen oder Dokumentation

Das Diagramm ist zu detailliert

Fragen Sie:

Vereinfachen Sie dieses PlantUML-Diagramm für einen architektonischen Überblick für Führungskräfte. Behalten Sie nur die wichtigsten Systeme, externen Abhängigkeiten und primären Datenflüsse bei. Entfernen Sie Klassen, Methoden, Infrastrukturdetails und Nachrichten auf Implementierungsebene.

KI ändert nicht verwandte Inhalte

Verwenden Sie enge Eingabeaufforderungen:

Ändern Sie nur den Zahlungsfluss. Benennen Sie Teilnehmer nicht um, ändern Sie keine bestehenden Beziehungen und verändern Sie keinen anderen Abschnitt.

Überprüfen Sie den generierten Diff, bevor Sie ihn akzeptieren.

KI erfindet Komponenten

Stellen Sie eine geschlossene Liste bereit:

Verwenden Sie nur diese Komponenten: Browser, API-Gateway, Bestelldienst, Zahlungsdienst, PostgreSQL und Zahlungsanbieter. Führen Sie keine zusätzlichen Dienste ein.

Das generierte Diagramm ist technisch plausibel, aber falsch

Fügen Sie der Eingabeaufforderung autoritatives Kontext hinzu, wie zum Beispiel:

• Tatsächliche Dienstnamen

• Eigentumsgrenzen

• Protokolle

• Datenspeicher

• Annahmen zur Authentifizierung

• Fehlverhalten

• Einschränkungen bei der Bereitstellung

Validieren Sie das Ergebnis anschließend mit dem Systemverantwortlichen oder dem Entwicklungsteam.

18. Empfohlener Workflow für Teams

Ein zuverlässiger Team-Workflow kombiniert die Geschwindigkeit der KI mit menschlicher Verantwortung:

Entdeckung

Beschreiben Sie das System in natürlicher Sprache und bitten Sie die KI um einen groben PlantUML-Entwurf.

Strukturierung

Fügen Sie explizite Grenzen, Aliasnamen, Titel und den Diagrammbereich hinzu.

Validierung

Vergleichen Sie das Diagramm mit Architektur-Dokumenten, Quellcode, API-Spezifikationen oder Diskussionen mit den Systemverantwortlichen.

Verfeinerung

Nutzen Sie die KI für gezielte Änderungen wie Gruppierung, Vereinfachung oder das Hinzufügen eines Fehlerpfads.

Überprüfung

Renden Sie das Ergebnis in VPasCode und prüfen Sie sowohl den Code als auch die visuelle Ausgabe.

Veröffentlichung

Exportieren Sie SVG oder PDF für die Dokumentation oder teilen Sie einen Live-Link, wenn dies angemessen ist.

Wartung

Speichern Sie die .pumlQuelle im Versionskontrollsystem und aktualisieren Sie sie, wenn sich das System ändert.

Das Schlüsselprinzip lautet:

Nutzen Sie die KI, um die Erstellung und Bearbeitung von Diagrammen zu beschleunigen, aber behalten Sie die menschliche Verantwortung für die architektonische Genauigkeit bei.

19. Praktische Checkliste

Bevor Sie ein VPasCode PlantUML-Diagramm veröffentlichen, überprüfen Sie Folgendes:

• Das Diagramm hat einen klaren Zweck.

• Der Titel beschreibt, was der Leser sieht.

• Die PlantUML-Quelle ist gespeichert.

• Der Code wird ohne Fehler gerendert.

• Namen und Aliasnamen sind konsistent.

• Grenzen sind visuell klar erkennbar.

• Externe Systeme werden von internen Systemen unterschieden.

• Beziehungen spiegeln die tatsächliche Architektur oder den Prozess wider.

• Fehlerpfade und alternative Pfade werden nur bei Bedarf einbezogen.

• Das Diagramm ist in der vorgesehenen Anzeigegröße lesbar.

• Unnötige Details wurden entfernt.

• KI-generierte Änderungen wurden überprüft.

• Das exportierte Format entspricht dem Zielort.

• Die Quelle wird zusammen mit der zugehörigen Dokumentation oder dem Code eingecheckt.

Fazit

VPasCode macht PlantUML zugänglicherdurch die Kombination von textbasiertem Diagrammieren, sofortiger Darstellung und KI-gestützter Generierung und Bearbeitungin einem einzigen Arbeitsbereich. Der produktivste Ansatz besteht nicht darin, die KI um ein fertiges Diagramm zu bitten und es blind zu akzeptieren. Stattdessen sollte die KI genutzt werden, um die leere Seite zu überwinden, wiederholende Syntax zu generieren, Fehler zu beheben, Beschriftungen zu übersetzen und kontrollierte Refaktorierungen durchzuführen.

Der stärkste Workflow ist:

Beschreiben → Generieren → Darstellen → Überprüfen → Verfeinern → Versionskontrolle → Veröffentlichen

PlantUML bleibt die strukturierte Quelle der Wahrheit, während VPasCode die interaktive Umgebung bereitstellt, um diese Quelle in klare, wartbare technische Diagramme zu verwandeln.