Das Problem, das Bausteinsicht löst

Architekturdokumentation veraltet. Das ist kein Meinungsproblem, das ist Praxis. Man zeichnet ein schönes C4-Diagramm, das System entwickelt sich weiter, und drei Monate später stimmt das Bild nicht mehr. Textbasierte Tools wie Structurizr oder LikeC4 lösen das Problem von der einen Seite: Text liegt im Git, ist versionierbar, diffbar, reviewbar. Aber man verliert die direkte visuelle Editierbarkeit.

Bausteinsicht versucht beide Seiten gleichzeitig zu halten: das Modell liegt als JSONC-Datei im Repository, draw.io ist das visuelle Frontend — und die Synchronisation läuft in beide Richtungen.

Das Datenmodell: drei Formate, ein Wahrheitsmodell

Intern arbeitet Bausteinsicht mit drei Formaten gleichzeitig:

FormatRolle

architecture.jsonc

Das Modell — Quelle für Elemente, Beziehungen, Views

architecture.drawio

Das Draw.io-XML — mehrere Pages, eine pro View

Go-Structs intern

Laufzeitrepräsentation für Sync-Logik und CLI-Output

Das JSONC-Modell hat drei Hauptbereiche: specification definiert die erlaubten Element-Typen und Beziehungsarten; model enthält die konkreten Elemente mit optionalem children-Baum für Hierarchien; views steuert, welche Elemente in welchem Diagramm auftauchen. Hier ein minimales Beispiel:

{
  "specification": {
    "elements": {
      "system":    { "notation": "Software System", "container": true },
      "container": { "notation": "Container" }
    },
    "relationships": {
      "uses": { "notation": "uses" }
    }
  },
  "model": {
    "shop": {
      "kind": "system", "title": "Online Shop",
      "children": {
        "api": { "kind": "container", "title": "REST API", "technology": "Go" },
        "db":  { "kind": "container", "title": "Database", "technology": "PostgreSQL" }
      }
    }
  },
  "views": {
    "containers": {
      "title": "Container View",
      "scope": "shop",
      "include": ["shop.*"]
    }
  }
}

Bidirektionale Synchronisation: das eigentlich schwierige Teil

Der sync-Befehl ist das Herzstück. Er muss Änderungen aus beiden Richtungen erkennen und zusammenführen — ohne Konflikte zu verlieren und ohne Layoutinformation zu zerstören, die der Benutzer manuell gesetzt hat.

Sync prozess bausteinsicht

Konkret: Fügt man im JSONC ein neues Element hinzu, erstellt sync den entsprechenden Knoten im Draw.io-XML. Verschiebt man umgekehrt einen Knoten in draw.io und speichert, liest sync die neue Position und schreibt sie ins Modell zurück. Was nicht überschrieben wird: manuell gesetzte Positionen und Größen, die nicht aus dem Modell stammen. Das ist das Merge-Problem, und es ist nicht trivial.

Ein weiteres Feature ist das Relationship Lifting. Wenn eine Beziehung zwischen zwei Elementen existiert, die beide nicht direkt in einer View sichtbar sind, hebt Bausteinsicht den Connector automatisch auf das nächste sichtbare Elternelement an. Das hält Views sauber, ohne Beziehungen aus dem Modell zu entfernen.

Das CLI: vollständig, LLM-tauglich

Die CLI ist von Anfang an so gebaut, dass sie nicht nur für Menschen, sondern auch für KI-Agenten benutzbar ist. Jeder Befehl unterstützt --format json, was maschinenlesbaren Output auf stdout und Fehler als strukturiertes JSON auf stderr liefert.

BefehlWas er tut

init

Legt Beispielmodell + Template an

sync

Bidirektionale Synchronisation JSONC ↔ draw.io

validate

Prüft Modellkonsistenz, gibt Fehler/Warnungen aus

watch

Kontinuierlicher Sync bei Dateiänderungen

add element

Element per CLI ins Modell einfügen (LLM-freundlich)

add relationship

Beziehung per CLI einfügen

export

PNG/SVG-Export über draw.io CLI

export-diagram

PlantUML-C4 oder Mermaid-C4 aus Views generieren

export-sequence

Sequenzdiagramme als PlantUML oder Mermaid

export-table

Elementattribute als AsciiDoc- oder Markdown-Tabelle

Das --format json-Flag an jedem Befehl war für meine Claude-Code-Workflows besonders nützlich: ich konnte Modellzustand maschinell abfragen und Issues direkt als strukturierte Änderungen einspielen, ohne Textparsing.

Meine Mitarbeit: Beta, Bugs, und 33 Issues

Ich war beim ersten Release als Beta-Tester dabei — Tool ausprobieren, Edge-Cases finden, kleine Fixes einbringen. Das lehrreiche daran: Man lernt die Grenzen eines Tools kennen, bevor man Features baut.

Danach habe ich systematisch GitHub-Issues erstellt — Feature-Requests, UX-Überlegungen, fehlende Exportformate, CLI-Ergonomie. 33 Issues, jedes mit klarem Scope. Den nächsten Schritt habe ich mit Claude Code gemacht: Issues als Arbeitsgrundlage nehmen, im Watch-Modus iterieren, Implementierungen direkt im Repository durchführen. In etwa zwei Tagen waren alle davon als Pull Requests umgesetzt.

Statistiken: 33 Issues

Was das Experiment gezeigt hat: Der Engpass ist nicht das Schreiben von Code, sondern das klare Denken davor. Ein Issue mit eindeutigem Scope und Akzeptanzkriterium funktioniert mit Claude Code hervorragend. Eine vage Idee ohne Kontext funktioniert nicht. Die Qualität des Inputs bestimmt die Qualität des Outputs — das gilt für KI-gestützte Entwicklung genauso wie für jede andere Art von Delegation.

Tutorial: Schritt für Schritt durch alle Features

Ich begleite das Release von Bausteinsicht mit einer 23-teiligen Tutorial-Serie — vom ersten Modell bis zu Health Score, Workspace-Setup und LLM-Workflows. Jeden Tag ein neuer Teil, ab 2026-06-11.

Zur Tutorial-Übersicht →

Ausprobieren

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/

bausteinsicht init
bausteinsicht sync

Weitere Infos und Dokumentation: https://github.com/docToolchain/Bausteinsicht