Jenseits statischer Bilder: Die Kraft von Diagramm-als-Code mit Mermaid und KI-Tools nutzen

Die Dokumentationskrise

Jedes Engineering-Team kennt die Schmerzen. Sie verbringen Wochen damit, eine wunderschöne Mikrodienste-Architektur zu entwerfen, sorgfältig Visio-Diagramme erstellend, die Stakeholder beeindrucken. Sechs Monate später hat sich das System weiterentwickelt – neue Dienste hinzugefügt, Datenbanken migriert, API-Endpunkte deaktiviert – doch das Diagramm ist in der Zeit eingefroren. Es ist ein Relikt. Fast eine Lüge.

Das ist die sogenannte ‘Dokumentationsverrottung’, und sie ist der stille Killer der Ingenieurproduktivität. Wenn Diagramme lügen, ignorieren Entwickler sie. Wenn Entwickler Dokumentation ignorieren, übernimmt das verbale Wissen. Wenn die eine Person, die das System kennt, geht, bleibt nur ein komplexer Codebase und keine Karte zurück.

Diagramm als Code (DaC)ist die Lösung. Und im Kern stehtMermaid, das JavaScript-basierte Diagramm-Tool, das einfachen Text in ansprechende Visualisierungen umwandelt.

Die zentrale Philosophie: Behandle Diagramme wie Software

Der grundlegende Wandel bei Diagramm als Code besteht darin, deine Diagramme mit derselben Sorgfalt zu behandeln wie deinen Anwendungscode. Das bedeutet:

1. Versionskontrolle ist Standard

Wenn dein Diagramm eine.mermaidDatei ist, dann befindet sie sich in deinem Git-Repository neben deinem Quellcode. Jede Änderung wird verfolgt. Du kannstgit blameverwenden, um zu sehen, wer diesen neuen Dienst hinzugefügt hat,git diffum Änderungen vor dem Merge zu überprüfen, und auf einen früheren Zustand zurückzugehen.

gitGraph
    commit id: "Ursprüngliche Architektur"
    commit id: "Benutzerdienst hinzufügen"
    branch feature/bezugsdienst
    commit id: "Bestellungs-Dienst v1"
    commit id: "Zahlungsgateway hinzufügen"
    checkout main
    merge feature/bezugsdienst
    commit id: "API-Gateway aktualisieren"

Beispiel: Visualisierung der eigenen Git-Geschichte des Diagramms mit der Git-Graph-Syntax von Mermaid

2. Code-Reviews für Diagramme

Pull Requests sind nicht mehr nur für Code. Wenn ein Entwickler einen neuen Dienst vorschlägt oder einen Datenfluss ändert, erscheint diese Änderung als lesbarer Unterschied im PR. Reviewer können direkt auf das Diagramm kommentieren, um sicherzustellen, dass architektonische Entscheidungen besprochen und genehmigt werden, bevor sie gemerged werden.

3. Integration in CI/CD-Pipelines

Deine Diagramme können automatisch in deiner Pipeline generiert und validiert werden. Stell dir eine GitHub Action vor, die:

• alle Mermaid-Diagramme als PNG/SVG rendert

• sie auf deine Dokumentationsseite hochlädt

• den Build fehlschlägt, wenn ungültige Mermaid-Syntax erkannt wird

flowchart LR
    A[Entwickler schiebt Code] --> B[CI-Pipeline wird ausgeführt]
    B --> C[Teste ausführen]
    B --> D[Mermaid-Diagramme rendern]
    D --> E{Gültige Syntax?}
    E -->|Ja| F[In Dokumentation hochladen]
    E -->|Nein| G[Build fehlschlagen & Team warnen]
    F --> H[Anwendung bereitstellen]
    G --> I[Entwickler behebt Syntax]
    I --> A

Beispiel: Ein CI/CD-Workflow für die Diagrammvalidierung und Bereitstellung

Mermaid in Aktion: Praxisbeispiele

Lassen Sie uns die Arten von Diagrammen erkunden, die Mermaid unterstützt, anhand praktischer, realer Beispiele.

Beispiel 1: Mikroservices-Architektur (Flussdiagramm)

Dies ist der häufigste Anwendungsfall – die Visualisierung der Kommunikation zwischen Ihren Diensten.

flowchart TB
    subgraph "Client-Ebene"
        MobileApp[Mobile-App]
        WebApp[Web-Anwendung]
    end

    subgraph "API-Gateway"
        Gateway[API-Gateway]
    end

    subgraph "Mikroservices"
        UserSvc[Benutzerdienst]
        OrderSvc[Bestellungs-Dienst]
        ProductSvc[Produktdienst]
        PaymentSvc[Zahlungsdienst]
    end

    subgraph "Daten-Ebene"
        UserDB[(Benutzer-Datenbank)]
        OrderDB[(Bestellungs-Datenbank)]
        ProductDB[(Produkt-Datenbank)]
        Redis[(Redis-Cache)]
    end

    subgraph "Externe Dienste"
        Stripe[Stripe-Zahlung]
        EmailAPI[Email-API]
    end

    MobileApp --> Gateway
    WebApp --> Gateway
    Gateway --> UserSvc
    Gateway --> OrderSvc
    Gateway --> ProductSvc
    Gateway --> PaymentSvc

    UserSvc --> UserDB
    UserSvc --> Redis
    OrderSvc --> OrderDB
    OrderSvc --> Redis
    ProductSvc --> ProductDB
    ProductSvc --> Redis

    PaymentSvc --> Stripe
    OrderSvc --> EmailAPI
    PaymentSvc --> EmailAPI

Beispiel: Eine vollständige Mikroservices-Architektur mit Caching, Datenbanken und externen Abhängigkeiten

Beispiel 2: Benutzer-Authentifizierungsablauf (Sequenzdiagramm)

Sequenzdiagramme sind ideal, um komplexe Interaktionen zwischen Diensten zu dokumentieren.

sequenceDiagram
    autonumber
    participant Benutzer
    participant Frontend
    participant AuthSvc als Auth-Dienst
    participant UserDB als Benutzer-Datenbank
    participant Cache als Redis-Cache
    participant EmailSvc als E-Mail-Dienst

    Benutzer->>Frontend: Anmeldeinformationen eingeben
    Frontend->>AuthSvc: POST /login (E-Mail, Passwort)
    AuthSvc->>UserDB: Benutzer per E-Mail abfragen
    UserDB-->>AuthSvc: Gespeicherte Passwort-Hash und Benutzerdaten zurückgeben
    AuthSvc->>AuthSvc: Passwort mit bcrypt überprüfen
    
    alt Gültige Anmeldeinformationen
        AuthSvc->>AuthSvc: Generiere JWT-Token
        AuthSvc->>Cache: Sitzung speichern (Schlüssel: user_id, TTL: 1 Stunde)
        AuthSvc-->>Frontend: 200 OK + JWT-Token
        Frontend-->>Benutzer: Weiterleitung zur Dashboard-Seite
    else Ungültige Anmeldeinformationen
        AuthSvc->>EmailSvc: Auslösen einer fehlgeschlagenen Anmeldung-Warnung
        AuthSvc-->>Frontend: 401 Unberechtigt
        Frontend-->>Benutzer: Fehlermeldung anzeigen
    end
    
    Note over AuthSvc,EmailSvc: Nach 5 fehlgeschlagenen Versuchen, Konto für 15 Minuten sperren

Beispiel: Ein detaillierter Authentifizierungsablauf, der Erfolgs- und Fehlschlagspfade zeigt, einschließlich Nebenwirkungen wie Caching und Warnungen

Beispiel 3: Cloud-Infrastruktur auf AWS (Klassendiagramm)

Klassendiagramme dienen nicht nur dem Code – sie können auch Cloud-Ressourcen und deren Beziehungen modellieren.

classDiagram
    class VPC {
        +string cidr_block
        +string region
        +createSubnet()
        +deleteSubnet()
    }

    class Subnet {
        +string availability_zone
        +string cidr_block
        +boolean is_public
        +attachRouteTable()
    }

    class EC2Instance {
        +string instance_type
        +string ami_id
        +int storage_gb
        +start()
        +stop()
        +reboot()
    }

    class RDSDatabase {
        +string engine
        +string version
        +int storage_gb
        +boolean multi_az
        +takeSnapshot()
        +restoreFromSnapshot()
    }

    class S3Bucket {
        +string bucket_name
        +string region
        +boolean versioning_enabled
        +uploadFile()
        +downloadFile()
    }

    class IAMRole {
        +string role_name
        +string policy_document
        +attachPolicy()
        +detachPolicy()
    }

    VPC "1" --> "*" Subnet
    Subnet "1" --> "*" EC2Instance
    Subnet "1" --> "0..1" RDSDatabase
    VPC "1" --> "0..*" S3Bucket
    EC2Instance --> IAMRole
    RDSDatabase --> IAMRole

Beispiel: Modellierung der AWS-Infrastruktur als Klassen mit Eigenschaften und Methoden, nützlich für Dokumentation und Planung von Infrastructure-as-Code

Beispiel 4: E-Commerce-Auftragsabwicklung (Zustandsdiagramm)

Zustandsdiagramme sind hervorragend geeignet, um zu zeigen, wie Entitäten durch verschiedene Zustände wechseln.

stateDiagram-v2
    [*] --> Warenkorb: Benutzer fügt Artikel hinzu
    Warenkorb --> Kasse: Benutzer geht zur Kasse
    
    Kasse --> ZahlungAusstehend: Benutzer sendet Bestellung
    ZahlungAusstehend --> ZahlungVerarbeitung: Zahlungsabwicklung starten
    
    ZahlungVerarbeitung --> Bezahlt: Zahlung erfolgreich
    ZahlungVerarbeitung --> Zahlungsfehler: Zahlung abgelehnt
    
    Zahlungsfehler --> Kasse: Benutzer versucht erneut zu zahlen
    Zahlungsfehler --> [*]: Benutzer verlässt Warenkorb
    
    Bezahlt --> Bestellbestätigt: Bestätigungs-E-Mail senden
    Bestellbestätigt --> Vorbereitung: Zu Lager zuweisen
    
    Vorbereitung --> Versandt: Übergabe an Versanddienstleister
    Versandt --> ImTransport: Versanddienstleister holt ab
    
    ImTransport --> Geliefert: Lieferung bestätigt
    Geliefert --> BewertungAngefragt: Benutzerbewertung anfordern
    
    BewertungAngefragt --> [*]: Benutzer gibt Bewertung ab
    Geliefert --> Rückerstattungsanfrage: Benutzer startet Rückerstattung
    
    Rückerstattungsanfrage --> RückerstattungGenehmigt: Support genehmigt
    RückerstattungGenehmigt --> RückerstattungAbgeschlossen: Geld zurückgezahlt
    RückerstattungAbgeschlossen --> [*]: Bestellung abgeschlossen
    
    Zustand "Hochriskante Betrugsprüfung" als Betrugsprüfung {
        [*] --> PrüfWert
        PrüfWert --> NiedrigesRisiko: Wert < 50
        PrüfWert --> HochesRisiko: Wert >= 50
        HochesRisiko --> ManuellePrüfung: Für Team markieren
        ManuellePrüfung --> NiedrigesRisiko: Genehmigt
        ManuellePrüfung --> Zahlungsfehler: Abgelehnt
    }
    
    ZahlungAusstehend --> Betrugsprüfung: Risikobewertung ausgelöst
    Betrugsprüfung --> ZahlungVerarbeitung: NiedrigesRisiko

Beispiel: Vollständige Zustandsmaschine für E-Commerce-Bestellungen mit eingebettetem Zustand zur Betrugserkennung

Beispiel 5: Sprint-Planung mit GitHub-Aufgaben (Git-Graph)

Git-Graphen können Workflows darstellen, die über Git hinausgehen.

gitGraph
    commit id: "Sprint-Planung" type: HIGHLIGHT
    
    branch sprint-1
    commit id: "Benutzerstory #101: Login-Seite"
    commit id: "Benutzerstory #102: Benutzerregistrierung"
    
    branch bugfix/hotfix
    commit id: "Hotfix: Ablauf des Auth-Tokens"
    checkout sprint-1
    merge bugfix/hotfix
    
    commit id: "Benutzerstory #103: Passwort zurücksetzen"
    
    checkout main
    merge sprint-1 tag: "v1.0.0"
    
    branch sprint-2
    commit id: "Funktion #201: Warenkorb"
    commit id: "Funktion #202: Kasse-Fluss"
    
    branch experiment/ai-empfehlungen
    commit id: "POC: ML-Empfehlungsmotor"
    
    checkout sprint-2
    commit id: "Funktion #203: Bestellhistorie"
    
    checkout main
    merge sprint-2 tag: "v2.0.0"
    
    commit id: "Versionshinweise: Sprint 1 & 2 abgeschlossen"

Beispiel: Projektmanagement, Sprints und Feature-Branches als Git-Graph visualisieren

Die KI-Revolution im Diagrammieren

Trotz der Eleganz von Mermaid kann die Syntax eine Hürde darstellen. Wer möchte schon einen falsch ausgerichteten Pfeil oder ein fehlendes Klammerzeichen debuggen, wenn man gerade ein System dokumentieren möchte?

Genau hier verändern KI-gestützte Werkzeuge alles.

KI-Auto-Fix

Werkzeuge wie VPasCode (Plattform von Visual Paradigm für Diagramme als Code) und Mermaid Chart haben KI-Modelle (wie Google Gemini und OpenAI) integriert, die können:

• Automatisch erkennen Syntaxfehler

• Beheben defekte Diagramme mit einem Klick beheben

• Vorschlagen Verbesserungen an der Diagrammstruktur

Schauen wir uns das in Aktion an:

Defekter Mermaid-Code:

flowchart LR
    A[Frontend] --> B(API-Gateway
    B --> C[Benutzerdienst]
    C --> D[(Datenbank
    D --> E[Cache]

AI-bereinigter Code:

Flussdiagramm LR
    A[Frontend] --> B(API-Gateway)
    B --> C[Benutzerdienst]
    C --> D[(Datenbank)]
    D --> E[Cache]

Die KI erkennt fehlende schließende Klammern und eckige Klammern und korrigiert sie sofort.

Natürliche Sprache zu Diagramm

Möglicherweise die leistungsstärkste Funktion ist die Erzeugung von Diagrammen aus natürlichen Sprachbeschreibungen. Mit Werkzeugen wie OpenDocs (Plattform für Dokumentation von VP), können Sie einfach beschreiben, was Sie wollen:

„Erstellen Sie ein Flussdiagramm, das zeigt, wie ein Benutzer sich anmeldet. Wenn die Anmeldeinformationen gültig sind, leiten Sie zur Übersichtsseite weiter. Wenn ungültig, zeigen Sie einen Fehler an und erlauben Sie 3 Versuche. Nach 3 Fehlversuchen sperren Sie das Konto.“

KI-generiertes Mermaid:

Flussdiagramm TD
    Start([Benutzer versucht sich anzumelden]) --> EnterCreds[E-Mail und Passwort eingeben]
    EnterCreds --> Validate{Anmeldeinformationen überprüfen}
    Validate -->|Gültig| Dashboard[Weiterleitung zur Übersichtsseite]
    Validate -->|Ungültig| CheckAttempts{Versuche < 3}
    CheckAttempts -->|Ja| Increment[Zähler für Versuche erhöhen]
    Increment --> ShowError[Fehlermeldung anzeigen]
    ShowError --> EnterCreds
    CheckAttempts -->|Nein| LockAccount[Konto für 15 Minuten sperren]
    LockAccount --> SendAlert[Sicherheitswarnung per E-Mail senden]
    SendAlert --> End([Prozess endet])
    Dashboard --> End

Übersetzung zwischen Diagrammtypen

KI kann auch zwischen verschiedenen Diagrammformaten übersetzen. Benötigen Sie ein PlantUML-Diagramm in Mermaid umgewandelt? KI-Tools können das bewältigen:

PlantUML-Eingabe:

@startuml
Aktivität Benutzer
Teilnehmer "Frontend" als FE
Teilnehmer "Backend" als BE
Datenbank "DB" als DB

Benutzer -> FE: Klicken auf Anmelden
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: Benutzerdaten
BE --> FE: JWT-Token
FE --> Benutzer: Übersichtsseite anzeigen
@enduml

KI-umgewandeltes Mermaid:

Ablaufdiagramm
    Aktivität Benutzer
    Teilnehmer Frontend
    Teilnehmer Backend
    Teilnehmer Datenbank
    
    Benutzer->>Frontend: Klicken auf Anmelden
    Frontend->>Backend: POST /login
    Backend->>Datenbank: SELECT user
    Datenbank-->>Backend: Benutzerdaten
    Backend-->>Frontend: JWT-Token
    Frontend-->>Benutzer: Übersichtsseite anzeigen

Interaktive Chatbot-Integration

Einige Plattformen bieten nun Chatbot-Oberflächen für die Diagrammerstellung. Sie können ein Gespräch führen:

Benutzer: „Fügen Sie einen neuen Dienst namens ‚Bestandsdienst‘ zu meinem Architekturdiagramm hinzu.“

KI: „Ich füge einen Bestandsdienst hinzu, der mit Ihren bestehenden Produkt- und Bestellungs-Diensten verbunden ist.“

Das Diagramm wird automatisch aktualisiert

Benutzer: „Eigentlich, stelle auch eine Verbindung zu einer neuen Datenbank namens ‚InventoryDB‘ her.“

KI: „Erledigt. Der Bestandsdienst ist nun mit dem Produkt-Dienst, dem Bestellungs-Dienst und der neuen Datenbank InventoryDB verbunden.“

Integrieren von Diagrammen als Code in Ihren Arbeitsablauf

Schritt 1: Fangen Sie klein an

Versuchen Sie nicht, Ihr gesamtes System auf einmal zu dokumentieren. Beginnen Sie mit einer einzelnen Komponente – vielleicht mit Ihrem Authentifizierungsablauf oder einer neuen Funktion, die Sie entwickeln.

Schritt 2: Einbetten in die Dokumentation

Behalten Sie Ihre .mermaid Dateien zusammen mit Ihrer Dokumentation (z. B. in einem /docs Ordner). Verwenden Sie Tools wie mermaid-cli um sie während des Build-Prozesses darzustellen.

Schritt 3: Nutzen Sie die einheitliche Engine von VPasCode

Wenn Sie in einem Team mit unterschiedlichen Vorlieben arbeiten, ist VPasCode unverzichtbar. Es unterstützt mehrere Diagramm-als-Code-Sprachen an einem Ort:

# In VPasCode können Sie beliebig kombinieren:
diagrams/
  ├── architecture.mermaid
  ├── deployment.puml      # PlantUML
  ├── database-erd.mermaid
  └── workflow.d2          # D2-Sprache

Schritt 4: Automatisieren mit CI/CD

Fügen Sie einen Schritt zu Ihren GitHub Actions oder GitLab CI hinzu:

- name: Mermaid-Diagramme rendern
  run: |
    for file in $(find docs -name "*.mermaid"); do
      npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
    done

- name: Hochladen auf Dokumentationsseite
  run: |
    aws s3 sync docs/ s3://your-docs-bucket/

Schritt 5: Überprüfung in Pull Requests

Machen Sie es zur Regel, dass alle Architekturänderungen Diagrammaktualisierungen erfordern. Verwenden Sie PR-Kommentare, um visuelle Änderungen zu besprechen:

Reviewer: „Sollte der Cache nicht zwischen dem Bestellungs-Dienst und der Datenbank stehen? Derzeit ist er nur mit dem Benutzer-Dienst verbunden.“

Autor:Guter Fund. Ich werde die Abbildung aktualisieren.

Wirkliche Auswirkungen: Ein Fallbeispiel

Stellen Sie sich einen Fintech-Startup vor, der Diagramm als Code mit Mermaid und VPasCode übernommen hat:

• Davor: 47 statische Visio-Dateien, die meisten älter als 6 Monate. Neue Mitarbeiter verbrachten 3 Wochen damit, die Architektur zu verstehen.

• Danach: 12 Mermaid-Abbildungen, alle in Git gespeichert und bei jeder Funktion aktualisiert. Neue Mitarbeiter waren bereits in der ersten Woche produktiv.

Der CTO des Teams bemerkte: „Wir sind von Diagrammen, die nur eine Compliance-Checkliste waren, zu einem lebendigen Bestandteil unseres Entwicklungsprozesses gewachsen. Wenn wir über eine neue Architektur diskutieren, öffnen wir den Mermaid-Editor und skizzieren sie buchstäblich im Code. Es ist ein Game-Changer.“

Die Zukunft: Kontinuierliche Dokumentation

Das ultimative Ziel ist die „kontinuierliche Dokumentation“, bei der Diagramme automatisch aus Ihrer Infrastruktur oder Ihrem Code generiert werden. Es entstehen bereits Werkzeuge, die können:

• Scannen Sie Ihre Kubernetes-Manifeste und generieren Sie Diensttopologie-Diagramme

• Parse OpenAPI/Swagger-Dateien und erstellen Sie API-Flussdiagramme

• Überwachen Sie Ihre Cloud-Ressourcen und aktualisieren Sie Architekturdiagramme automatisch

Mermaid steht im Zentrum dieser Bewegung und bietet ein einfaches, textbasiertes Format, das Maschinen generieren und Menschen verstehen können.

Heute loslegen

Bereit, über statische Bilder hinauszugehen? Hier ist Ihr Aktionplan:

1. Installieren Sie die Mermaid-Erweiterung in Ihrer Lieblings-IDE (VS Code, IntelliJ)

2. Erstellen Sie Ihr erstes Diagramm in einer .md Datei mit Mermaids Syntax

3. Erkunden Sie die kostenlose Version von VPasCode um die künstliche Intelligenz-gestützte Diagrammerstellung zu erleben

4. Beginnen Sie mit einem lebendigen Dokumentations-Repository neben Ihrem Code-Repository

5. Teilen Sie diesen Artikel mit Ihrem Team und beginnen Sie die Diskussion

Ihre Architektur verdient mehr als ein staubiges Diagramm in einem vergessenen Ordner. Es ist Zeit, Ihre Diagramme wie die kritischen Assets zu behandeln, die sie sind.