Teil 2: Von 0 zum ersten Architekturdiagramm mit Bausteinsicht

Dieser Post setzt den ersten Teil fort. Dort ging es darum, was Architecture-as-Code ist und was Bausteinsicht von anderen Tools unterscheidet. Hier wird es praktisch: Installation, erstes Projekt, erstes Diagramm.

Voraussetzungen

Bausteinsicht Binary (Linux, macOS oder Windows)
draw.io Desktop oder die draw.io VS Code Extension
Ein Editor mit JSON-Support (VS Code empfohlen)

Installation

# Aktuelle Version automatisch ermitteln (Linux amd64)
VER=$(curl -s https://api.github.com/repos/docToolchain/Bausteinsicht/releases/latest \
      | grep '"tag_name"' | cut -d'"' -f4 | sed 's/^v//')
curl -Lo bausteinsicht.tar.gz \
  "https://github.com/docToolchain/Bausteinsicht/releases/download/v${VER}/Bausteinsicht_${VER}_linux_amd64.tar.gz"
tar xzf bausteinsicht.tar.gz && sudo mv bausteinsicht /usr/local/bin/

# macOS (Apple Silicon)
curl -Lo bausteinsicht.tar.gz \
  "https://github.com/docToolchain/Bausteinsicht/releases/download/v${VER}/Bausteinsicht_${VER}_darwin_arm64.tar.gz"
tar xzf bausteinsicht.tar.gz && sudo mv bausteinsicht /usr/local/bin/

# Go Install (alle Plattformen — immer neueste Version)
go install github.com/docToolchain/Bausteinsicht/cmd/bausteinsicht@latest

Prüfen ob die Installation funktioniert:

bausteinsicht --version

Schritt 1: Projekt initialisieren

Neuen Ordner anlegen und Bausteinsicht initialisieren:

mkdir meine-architektur && cd meine-architektur
bausteinsicht init

init erzeugt vier Dateien:

Datei Zweck

Datei	Zweck
`architecture.jsonc`	Das Architekturmodell — die einzige Quelle der Wahrheit
`architecture.drawio`	Das generierte draw.io-Diagramm
`template.drawio`	Visuelle Stile für Element-Typen (Farben, Formen)
`.bausteinsicht-sync`	Sync-State-Datei — gehört ins Git neben dem Modell

architecture.jsonc

Das Architekturmodell — die einzige Quelle der Wahrheit

architecture.drawio

Das generierte draw.io-Diagramm

template.drawio

Visuelle Stile für Element-Typen (Farben, Formen)

.bausteinsicht-sync

Sync-State-Datei — gehört ins Git neben dem Modell

Schritt 2: Das generierte Modell verstehen

Bausteinsicht legt ein Beispiel-Modell eines Online-Shops an. Öffne architecture.jsonc im Editor — du siehst die drei Hauptbereiche:

{
  "specification": {
    "elements": {
      "actor":     { "notation": "Actor" },
      "system":    { "notation": "Software System", "container": true },
      "container": { "notation": "Container", "container": true },
      "component": { "notation": "Component", "container": true }
    },
    "relationships": {
      "uses":  { "notation": "uses" },
      "reads": { "notation": "reads", "dashed": true }
    }
  },

  "model": {
    "customer": { "kind": "actor", "title": "Customer" },
    "onlineshop": {
      "kind": "system", "title": "Online Shop",
      "children": {
        "frontend": { "kind": "container", "title": "Web Frontend",  "technology": "React" },
        "api":      { "kind": "container", "title": "REST API",       "technology": "Go"    },
        "db":       { "kind": "container", "title": "Database",       "technology": "PostgreSQL" }
      }
    }
  },

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

specification definiert die Sprache des Modells. model beschreibt das konkrete System. views steuert welche Elemente in welchem Diagramm auftauchen.

Das Modell validieren:

bausteinsicht validate

Ausgabe: Model is valid.

Schritt 3: Das Diagramm öffnen

architecture.drawio in draw.io öffnen. Du siehst zwei Tabs:

System Context — Customer und Online Shop auf der obersten Ebene
Container View — die internen Container des Online Shops

Neue Elemente erscheinen mit rotem gestricheltem Rahmen als visueller Marker. Positionen lassen sich per Drag & Drop anpassen — Bausteinsicht merkt sich die gesetzten Positionen bei der nächsten Synchronisation.

Das Layout ist bewusst manuell — und das ist ein Feature, keine Einschränkung. Bausteinsicht übernimmt die Positionen nicht automatisch, weil kein Algorithmus weiß, welche räumliche Nähe in deinem Diagramm Bedeutung trägt. Du entscheidest, welche Elemente zusammengehören und wie die Lesrichtung fließt. Einmal gesetzt bleiben die Positionen bei jedem sync erhalten — du musst nie neu layouten, solange du keine neuen Elemente hinzufügst. Wer dennoch automatisch anordnen möchte, kann bausteinsicht sync --relayout nutzen — das setzt alle Positionen zurück und wendet das hierarchische Auto-Layout an. Details dazu in Teil 14: Auto-Layout.

Schritt 4: Element per CLI hinzufügen

Einen neuen Email-Service zum Modell hinzufügen:

bausteinsicht add element \
  --id emailservice \
  --kind container \
  --title "Email Service" \
  --technology "Go" \
  --parent onlineshop \
  --description "Sendet transaktionale E-Mails"

Ausgabe: Added element 'onlineshop.emailservice' (kind: container) to model.

Jetzt eine Beziehung vom REST API zum Email Service anlegen:

bausteinsicht add relationship \
  --from onlineshop.api \
  --to onlineshop.emailservice \
  --label "sendet E-Mails" \
  --kind uses

Schritt 5: Modell → Diagramm synchronisieren

bausteinsicht sync

Ausgabe:

Forward (model → draw.io): 2 added, 0 updated, 0 deleted

architecture.drawio in draw.io neu laden — der Email Service erscheint mit rotem Rahmen in der Container View.

Schritt 6: Diagramm → Modell synchronisieren

Jetzt die andere Richtung: eine Änderung im Diagramm zurück ins Modell schreiben.

In draw.io architecture.drawio öffnen
Doppelklick auf „Web Frontend"
Titel ändern auf „Web App"
Datei speichern

bausteinsicht sync

Ausgabe:

Reverse (draw.io → model): 0 added, 1 updated, 0 deleted

architecture.jsonc öffnen — der Titel ist auf "Web App" aktualisiert. Das ist bidirektionale Synchronisation in der Praxis.

Schritt 7: Watch-Modus

Für kontinuierliche Synchronisation während der Arbeit:

bausteinsicht watch

Bausteinsicht überwacht beide Dateien und synct automatisch bei jeder Änderung. Damit kann man im Editor und in draw.io gleichzeitig arbeiten — ohne manuelles sync. Ctrl+C beendet den Watch-Modus.

watch eignet sich gut für Workshops und Review-Sessions: mehrere Personen können gleichzeitig Modell und Diagramm bearbeiten, der Watch-Prozess hält alles in Sync.

Beispiel-Modell

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

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

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

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

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Was als nächstes kommt

Teil 3: Das Datenmodell im Detail — specification, model, views und alle verfügbaren Felder
Teil 4: Bidirektionale Synchronisation — wie der Merge-Algorithmus funktioniert und was passiert wenn beide Seiten gleichzeitig geändert wurden

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org

Voraussetzungen#

Installation#

Schritt 1: Projekt initialisieren#

Schritt 2: Das generierte Modell verstehen#

Schritt 3: Das Diagramm öffnen#

Schritt 4: Element per CLI hinzufügen#

Schritt 5: Modell → Diagramm synchronisieren#

Schritt 6: Diagramm → Modell synchronisieren#

Schritt 7: Watch-Modus#

Beispiel-Modell#

Was als nächstes kommt#