Das Grundproblem: Dokumentation veraltet

Software-Architektur wird meistens einmal dokumentiert — beim Start des Projekts, wenn der Architekt noch motiviert ist und das System noch überschaubar. Drei Monate später sieht die Realität anders aus. Ein neuer Service ist dazugekommen. Eine Abhängigkeit wurde umgezogen. Das alte Diagramm zeigt noch die ursprüngliche Idee, nicht das aktuelle System.

Das Problem ist strukturell: Diagramme leben in Präsentationen, Wikis oder Draw.io-Dateien. Code lebt im Repository. Die beiden Welten synchronisieren sich nicht automatisch — also driften sie auseinander.

Architecture-as-Code: Text als Quelle der Wahrheit

Die Antwort der Architecture-as-Code-Bewegung: Architektur gehört ins Repository, neben dem Code. Textbasierte Beschreibung, versionierbar, reviewbar, diffbar. Wenn ein Service hinzukommt, ändert sich auch das Architekturmodell — im selben Commit, im selben Pull Request.

Das Prinzip funktioniert. Was es schwieriger macht: Textmodelle sind keine Diagramme. Architekten und Teams denken visuell. Ein YAML-File, das einen Graphen beschreibt, ist korrekt — aber nicht intuitiv navigierbar.

Die zwei Lager: Text-first vs. Visual-first

Bestehende Tools lösen das Problem jeweils von einer Seite:

ToolStärkeSchwäche

Structurizr

Eigene DSL, strukturiertes C4-Modell, viele Exportformate

Kein visuelles Editieren — Text ist die einzige Quelle

LikeC4

Moderne DSL, VS Code Extension, Live-Vorschau

Diagramm ist Output, kein editierbares Frontend

C4 model

Klare Methodologie (Context, Container, Component, Code)

Kein Tool, nur ein Rahmenwerk

C4InterFlow

Erweitert C4 um Interface- und Flow-Konzepte

Sehr spezifisch auf Interaktionsmodellierung ausgerichtet

Der gemeinsame Nenner: Text ist die Quelle, Diagramm ist der Output. Das Diagramm selbst kann nicht editiert werden, zumindest nicht auf eine Weise die zurück ins Modell fließt.

Was Bausteinsicht anders macht: Bidirektionale Synchronisation

Bausteinsicht dreht die Frage um: Warum muss man sich entscheiden?

Das Modell liegt als JSONC-Datei im Repository — textbasiert, versionierbar, LLM-lesbar. draw.io ist das visuelle Frontend — ein weit verbreitetes, ausgereifte Diagrammwerkzeug. Beide Seiten sind gleichwertig. Änderungen im Text fließen ins Diagramm. Änderungen im Diagramm fließen zurück in den Text.

# Modell ändern → Diagramm aktualisieren
bausteinsicht sync

# Diagramm in draw.io editieren → Modell aktualisieren
bausteinsicht sync

# Kontinuierlich bei jeder Dateiänderung
bausteinsicht watch

Das ist kein Export. Das ist ein Merge: Positionen, Labels, neue Elemente — der sync-Befehl erkennt was sich geändert hat und führt beide Seiten zusammen, ohne die jeweils andere Seite zu überschreiben.

Das Modell: JSONC mit drei Sektionen

Das Herzstück ist eine architecture.jsonc — JSON mit Kommentaren. Drei Sektionen definieren alles:

{
  "specification": {
    "elements": {
      "system":    { "notation": "Software System", "container": true },
      "container": { "notation": "Container", "container": true }
    },
    "relationships": {
      "uses": { "notation": "uses" }
    }
  },

  "model": {
    "shop": {
      "kind": "system", "title": "Online Shop",
      "children": {
        "api":      { "kind": "container", "title": "REST API", "technology": "Go" },
        "frontend": { "kind": "container", "title": "Web Frontend", "technology": "React" }
      }
    }
  },

  "views": {
    "context":    { "title": "Context View",   "include": ["shop"] },
    "containers": { "title": "Container View", "scope": "shop", "include": ["shop.*"] }
  }
}

specification definiert die Sprache: welche Arten von Elementen und Beziehungen im Modell existieren können. model enthält die konkreten Systemelemente mit beliebig tiefer Hierarchie. views steuert, welche Elemente in welchem Diagramm auftauchen — ein Element kann in mehreren Views erscheinen.

Warum draw.io als Frontend?

Draw.io ist kein zufälliger Kandidat:

  • Weit verbreitet — viele Teams haben es bereits im Einsatz

  • Offline-fähig, keine Cloud-Abhängigkeit

  • XML-basiertes Format, das programmatisch gelesen und geschrieben werden kann

  • Freie Positionierung und visuelle Anpassung möglich

Der entscheidende Punkt ist das Format: draw.io-Dateien sind unkomprimiertes XML. Bausteinsicht kann das XML gezielt lesen, Elemente zuordnen, Positionen mergen und das Ergebnis zurückschreiben — ohne die Draw.io-Applikation zu öffnen.

Das macht bidirektionale Synchronisation technisch möglich. Mit einem proprietären Binary-Format wäre es das nicht.

Beispiel-Modell

Das Beispiel für diesen Teil ist als ausführbare JSONC-Datei unter teil_1.jsonc abgelegt.

So sieht das Ergebnis in draw.io aus (bausteinsicht sync):

Das draw.io-File dafür findest du hier: teil_1.drawio

Generierte PNG-Dateien via bausteinsicht export --image-format png:

containers
context

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Diagram
Diagram

Was als nächstes kommt

Dieser Post gibt einen Überblick — die folgenden Posts gehen in die Tiefe:

Wer direkt loslegen will:

# Installation (Linux amd64)
curl -Lo bausteinsicht.tar.gz \
  https://github.com/docToolchain/Bausteinsicht/releases/latest/download/bausteinsicht_linux_amd64.tar.gz
tar xzf bausteinsicht.tar.gz && sudo mv bausteinsicht /usr/local/bin/

# Erstes Projekt
mkdir meine-architektur && cd meine-architektur
bausteinsicht init
bausteinsicht sync

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org