Diagrams as Code und aktuelle Dokumentation

Was Diagrams as Code bedeutet

Diagrams as Code bedeutet, ein Diagramm als kurze Textdatei in einer kleinen Sprache zu schreiben und es von einem Werkzeug anordnen und zeichnen zu lassen. Statt Kästen auf einer Zeichenfläche zu verschieben, schreiben Sie ordering -> db: SQL, und das Werkzeug erzeugt das Bild. Die Textdatei liegt im Code-Repository und wird wie Code behandelt: versioniert, geprüft, von automatisierten Builds getestet und von der Pipeline veröffentlicht.

Es ist ein Teil von Docs as Code, der von der Community Write the Docs vorangetriebenen Praxis, Dokumentation mit denselben Werkzeugen und demselben Arbeitsablauf wie Software zu erstellen: Issue-Tracker, Versionskontrolle (meist Git), Klartext-Auszeichnungssprachen wie Markdown oder AsciiDoc, Code-Review und automatisierte Tests. Die vorigen Abschnitte haben das Material geliefert: Sichten und C4-Diagramme, UML, wo Präzision zählt, ADRs und eine arc42-Struktur. In diesem Abschnitt geht es darum, dieses Material über die gesamte Lebensdauer des Systems korrekt zu halten, und genau daran scheitert die meiste Architekturdokumentation. Die Gründe für dieses Scheitern wurden in Warum und wie viel dokumentieren dargelegt: veraltete Wikis, große Dokumente, für die niemand verantwortlich ist, und Diagramme, die nicht mehr zum System passen.

Warum Diagramme als Text

Versionskontrolle. Ein Diagramm in Textform hat eine Historie. Sie sehen, wer es wann und warum geändert hat, und können zwei beliebige Versionen Zeile für Zeile vergleichen; ein Binärbild oder eine Datei im Format eines Zeichenwerkzeugs zeigt nur, dass sich etwas geändert hat. Sie können es auch verzweigen: Das Diagramm für eine vorgeschlagene Änderung liegt auf demselben Branch wie der Code, der sie umsetzt.

Review in Pull Requests. Wenn eine Entwicklerin oder ein Entwickler eine neue Abhängigkeit zwischen Services einführt, erscheint die Änderung am Diagramm im selben Pull Request wie der Code, als lesbarer Text-Diff. Die Reviewer können fragen, ob der neue Pfeil gewollt ist, und das ist ein Architektur-Review genau in dem Moment, in dem es am wenigsten kostet.

Konsistenz. Das Werkzeug wendet auf jedes Diagramm dieselben Formen, Schriften und Layoutregeln an, sodass Diagramme von zwanzig Personen trotzdem wie ein zusammengehöriger Satz aussehen. Mit einer Modellierungssprache (siehe unten) erscheint dasselbe Element in jeder Sicht mit demselben Namen und derselben Beschreibung.

Generierung. Text kann von Programmen erzeugt werden. Diagramme lassen sich aus dem Code selbst (Abhängigkeitsgraphen), aus Infrastructure as Code (Deployment-Diagramme), aus API-Spezifikationen oder aus einem zentralen Modell generieren und dann automatisch gegen das System prüfen.

Die Abwägungen sind real. Automatisches Layout ist bequem, aber manchmal hässlich, und der Kampf mit einer Layout-Engine um die Position eines einzigen Kastens kann länger dauern, als ihn zu zeichnen; die meisten Werkzeuge bieten Hinweise wie Richtung oder Gruppierung, keine exakten Positionen. Textsprachen haben eine Lernkurve für Menschen, die nicht programmieren, etwa im Produktmanagement. Und eine schöne Skizze am Whiteboard während einer Designdiskussion ist immer noch der schnellste Weg zu denken; Diagrams as Code sind für die Diagramme gedacht, die Sie behalten wollen.

Vier Sprachen, ein Beispiel

Vier Sprachen dominieren. Jedes Beispiel unten beschreibt einen Teil derselben Essenslieferplattform.

PlantUML, von Arnaud Roques entwickelt und 2009 erstmals veröffentlicht, ist die älteste der vier. Es deckt alle gängigen UML-Diagramme ab (Sequenz-, Komponenten-, Deployment-, Zustands-, Aktivitäts- und Klassendiagramm) und viele weitere und nutzt Graphviz für das Layout der meisten Diagrammtypen. Die Bibliothek C4-PlantUML ergänzt C4-Formen. Seine Sequenzdiagramme sind besonders gut, was es zur naheliegenden Wahl für die Laufzeitszenarien aus UML-Grundlagen macht.

@startuml
title Place an order (happy path)
actor Customer
participant "Customer app" as App
participant "Ordering service" as Ord
participant "Payment provider" as Pay
queue "Order events topic" as MB

Customer -> App : Tap "Pay"
App -> Ord : POST /orders (HTTPS)
Ord -> Pay : Authorise payment
Pay --> Ord : Authorised
Ord ->> MB : OrderPlaced (async)
Ord --> App : 201 Created
@enduml

Mermaid, 2014 von Knut Sveidqvist entwickelt, ist in JavaScript geschrieben und wird im Browser gerendert. Sein größter Vorteil ist die Verbreitung: GitHub rendert Mermaid-Blöcke in Markdown-Dateien seit Februar 2022, und GitLab sowie viele Wiki- und Notizwerkzeuge tun dasselbe, sodass ein Diagramm in einer README überhaupt keinen Build-Schritt braucht. Es unterstützt unter anderem Flussdiagramme, Sequenz-, Klassen-, Zustands- und Entity-Relationship-Diagramme und hat experimentelle C4-Unterstützung. Bei großen Diagrammen ist die Kontrolle über das Layout begrenzt.

flowchart LR
    app["Customer app<br/>Kotlin, Swift"]
    gw["API gateway"]
    ord["Ordering service<br/>Java"]
    db[("Order database<br/>PostgreSQL")]
    topic[["Order events<br/>Kafka topic"]]
    disp["Dispatch service<br/>Go"]
    notif["Notification service<br/>Node.js"]

    app -->|HTTPS/JSON| gw
    gw -->|HTTPS/JSON| ord
    ord -->|SQL| db
    ord -->|publishes OrderPlaced| topic
    disp -->|consumes| topic
    notif -->|consumes| topic

Structurizr DSL, von Simon Brown parallel zum C4-Modell entwickelt, ist grundsätzlich anders. Es beschreibt kein Diagramm, sondern ein Modell (Personen, Softwaresysteme, Container, Komponenten und die Beziehungen zwischen ihnen) und definiert dann Sichten auf dieses Modell. Jedes Element wird einmal definiert, mit Name, Beschreibung und Technologie, und erscheint in jeder Sicht, die es enthält. Beziehungen zwischen Containern werden auf Systemebene automatisch abgeleitet, sodass die Kontextsicht keine eigenen Pfeile braucht. Die DSL kann dem Workspace außerdem Markdown-Dokumentation und einen Ordner mit ADRs zuordnen, und die Werkzeuge können Sichten nach PlantUML, Mermaid, D2 und in andere Formate exportieren.

workspace "Food delivery" {
    model {
        customer = person "Customer" "Orders food from local restaurants."
        payments = softwareSystem "Payment provider" "Takes card payments." "External"
        platform = softwareSystem "Food-delivery platform" {
            app = container "Customer app" "Ordering and tracking." "Kotlin, Swift"
            gateway = container "API gateway" "Authenticates and routes requests." "Managed API gateway"
            ordering = container "Ordering service" "Accepts and tracks orders." "Java"
            db = container "Order database" "Orders and their states." "PostgreSQL" "Database"
            orderEvents = container "Order events" "Order lifecycle events." "Kafka topic" "Topic"
            dispatch = container "Dispatch service" "Assigns couriers." "Go"
        }
        customer -> app "Places and tracks orders using"
        app -> gateway "Makes API calls to" "JSON/HTTPS"
        gateway -> ordering "Routes requests to" "JSON/HTTPS"
        ordering -> db "Reads from and writes to" "SQL/TCP"
        ordering -> payments "Takes card payments using" "JSON/HTTPS"
        ordering -> orderEvents "Publishes order events to" "Kafka"
        dispatch -> orderEvents "Consumes order events from" "Kafka"
    }
    views {
        systemContext platform "Context" {
            include *
            autoLayout lr
        }
        container platform "Containers" {
            include *
            autoLayout lr
        }
        styles {
            element "Database" {
                shape cylinder
            }
            element "Topic" {
                shape pipe
            }
        }
    }
}

D2 (Declarative Diagramming), 2022 von Terrastruct als Open Source veröffentlicht, ist die jüngste. Sie zielt auf saubere, moderne Ausgabe und lesbare Syntax, unterstützt verschachtelte Container (mit geschweiften Klammern geschrieben und mit Punktnamen referenziert) und bietet eine Auswahl an Layout-Engines: dagre und ELK sind enthalten und kostenlos, und TALA, für Softwarearchitekturdiagramme entworfen, ist eine separate kommerzielle Engine.

direction: right

customer: Customer {shape: person}
payments: Payment provider

platform: Food-delivery platform {
  app: Customer app
  ordering: Ordering service
  db: Order database {shape: cylinder}
  events: Order events topic {shape: queue}
  dispatch: Dispatch service

  app -> ordering: Places order (HTTPS)
  ordering -> db: SQL
  ordering -> events: Publishes OrderPlaced
  dispatch -> events: Consumes OrderPlaced
}

customer -> platform.app: Places orders using
platform.ordering -> payments: Authorise (HTTPS)

Zeichenwerkzeuge und Modellierungswerkzeuge

Der Unterschied zwischen Structurizr und den anderen drei ist ein Fall der in Abschnitt 4.3 eingeführten Unterscheidung zwischen Zeichen- und Modellierungswerkzeugen. Ein Zeichenwerkzeug (diagrams.net, Excalidraw, Visio, ein Online-Whiteboard und auch PlantUML, Mermaid und D2) kennt Formen, Linien und Text. Ein Kasten mit der Beschriftung Bestellservice in einem Diagramm hat keine Verbindung zum gleich beschrifteten Kasten in einem anderen. Benennen Sie den Service um, müssen Sie jedes Diagramm von Hand suchen und korrigieren; vertippen Sie sich einmal, haben Sie, soweit das Werkzeug weiß, zwei Services.

Ein Modellierungswerkzeug (Structurizr, Archi für ArchiMate-Modelle, Sparx Enterprise Architect für UML und SysML, Capella) führt ein Modell: ein Repository von Elementen und Beziehungen mit Eigenschaften. Diagramme sind Sichten auf das Modell. Benennen Sie ein Element um, ändert sich jede Sicht. Das Modell lässt sich abfragen (Welche Container hängen vom Broker ab?), prüfen (Keine Komponente der Kunden-App darf die Datenbank aufrufen) und mit dem laufenden System vergleichen. Der Preis ist mehr Struktur im Voraus und, bei den schwergewichtigen kommerziellen Werkzeugen, Lizenzen, Schulungen und die Neigung, weit mehr zu modellieren, als jemand liest.

Eine praktische Regel: Verwenden Sie Zeichenwerkzeuge, textbasiert oder grafisch, für Skizzen, einmalige Erklärungen und Diagramme, die für sich stehen, etwa ein einzelnes Sequenzdiagramm in einem ADR. Verwenden Sie ein Modell, wenn dieselben Elemente in vielen Diagrammen vorkommen, wenn mehrere Teams beitragen oder wenn Sie die Dokumentation gegen den Code prüfen wollen. Viele Teams kombinieren beides: ein Structurizr-Modell für die C4-Struktur und PlantUML oder Mermaid für einige Sequenz- und Zustandsdiagramme.

Dokumentation in der Pipeline erzeugen

Sobald Dokumentation als Text im Repository liegt, kann die Continuous-Integration-Pipeline aus Kapitel 0 sie wie Code bauen und prüfen. Eine typische Pipeline rendert jedes Diagramm (und lässt den Build bei einem Syntaxfehler scheitern), prüft Links, baut mit einem Generator wie MkDocs, Antora oder Docusaurus eine statische Dokumentationssite und veröffentlicht sie, sobald Änderungen den Main-Branch erreichen. Lesende sehen dann immer die Dokumentation, die zum Code auf main passt, und niemand muss daran denken, ein Bild zu exportieren und in ein Wiki hochzuladen.

Weitere Prüfungen kommen hinzu, wenn das Team reifer wird: eine Rechtschreibprüfung und ein Prosa-Linter (Vale ist beliebt), eine Prüfung, dass jedes ADR einen gültigen Status hat, eine Warnung, wenn das Datum der letzten Prüfung einer Seite älter als ihr Prüfintervall ist, und Architekturprüfungen, die die dokumentierten Abhängigkeiten mit den tatsächlichen im Code vergleichen und eine Form von Fitness Function sind. Manche Teams generieren Teile der Dokumentation aus dem System selbst: Abhängigkeitsgraphen aus dem Build, API-Referenzen aus OpenAPI-Spezifikationen, Deployment-Diagramme aus Infrastructure as Code.

name: architecture-docs
on:
  pull_request:
    paths: ["docs/**"]
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # assumes plantuml, d2, lychee and mkdocs are available on the runner
      - name: Render diagrams (fails on syntax errors)
        run: |
          plantuml -tsvg docs/diagrams/*.puml
          for f in docs/diagrams/*.d2; do d2 "$f" "${f%.d2}.svg"; done
      - name: Check links
        run: lychee --offline docs/
      - name: Build site (warnings such as broken links fail the build)
        run: mkdocs build --strict
      - name: Publish
        if: github.ref == 'refs/heads/main'
        run: ./scripts/publish-docs.sh

Dokumentation aktuell halten

Werkzeuge halten Dokumentation nicht wahr, Gewohnheiten schon. Fünf Gewohnheiten machen den Unterschied.

Verantwortung. Jedes Dokument hat einen namentlich benannten Owner, normalerweise das Team, dem der beschriebene Code gehört. In GitHub und GitLab kann eine CODEOWNERS-Datei dieses Team zum Pflicht-Reviewer für Änderungen in seinem Ordner docs/ machen. Dokumente, für die alle verantwortlich sind, pflegt niemand.

Review mit Codeänderungen. Eine Pull-Request-Vorlage, die fragt: Ändert dies eine Schnittstelle, eine Abhängigkeit, ein Deployment oder eine Entscheidung? Wenn ja, welches Dokument oder ADR haben Sie aktualisiert?, fängt den meisten Drift genau dann ab, wenn er entsteht. Manche Teams gehen weiter und blockieren das Mergen von Features ohne Dokumentation, eine Praxis, die der Leitfaden von Write the Docs erwähnt.

Datum der letzten Prüfung. Ein kleiner Kopfbereich auf jeder Seite hält ihren Owner fest, das Datum, an dem sie zuletzt mit der Wirklichkeit abgeglichen wurde, und wie oft sie geprüft werden soll. Lesende können einschätzen, wie weit sie ihr trauen können, und die Pipeline kann überfällige Seiten markieren. Eine Seite mit zuletzt geprüft 2023 ist ehrlich; eine Seite, die stillschweigend das System von 2023 beschreibt, ist eine Falle.

Dokumentation und Code verknüpfen. Seiten verweisen auf den Code, den sie beschreiben (Pfade, Module), Code-Kommentare verweisen auf ADRs, und Commit-Nachrichten nennen die Records, die sie umsetzen. Links in beide Richtungen machen offensichtlich, welche Dokumente eine Änderung betreffen könnte.

Veraltetes Material löschen. Falsche Dokumentation ist schlimmer als keine, weil Lesende danach handeln. Wenn eine Seite das System nicht mehr beschreibt und niemand sie korrigieren wird, löschen Sie sie oder verschieben Sie sie in ein klar gekennzeichnetes Archiv. ADRs sind die Ausnahme: Sie sind Aufzeichnungen der Geschichte und werden daher ersetzt oder als veraltet markiert, nicht gelöscht. Das ist die Idee der lebenden Dokumentation, die Cyrille Martraire 2019 in seinem gleichnamigen Buch entwickelt hat: Dokumentation, die sich im selben Tempo wie das System weiterentwickelt, idealerweise weil vieles davon aus dem System abgeleitet wird.

---
title: "Ordering service: building block view (level 2)"
owner: "@ordering-team"
last_reviewed: 2026-09-14
review_every: 6 months
code: src/ordering/
decisions: [ADR-0007, ADR-0012]
---