Dieser Post setzt den siebzehnten Teil fort. Das Modell lässt sich nicht nur manuell in architecture.jsonc bearbeiten — alle strukturellen Änderungen gehen auch über die CLI. Das ist besonders nützlich für Skripte, LLM-Workflows (→ Teil 10) und CI-Pipelines.

bausteinsicht add element

Neues Element zum Modell hinzufügen:

# Top-Level-Element
bausteinsicht add element \
  --id paymentservice \
  --kind service \
  --title "Payment Service" \
  --technology "Go" \
  --description "Verarbeitet Zahlungen"

# Verschachteltes Element (child von paymentservice)
bausteinsicht add element \
  --id ledger \
  --kind database \
  --title "Payment Ledger" \
  --technology "PostgreSQL" \
  --parent paymentservice

Validierungen: * --id darf nur Buchstaben, Ziffern, Bindestriche, Unterstriche enthalten (keine Punkte — Punkte sind Hierarchietrennzeichen) * --kind muss in specification.elements definiert sein * Parent muss existieren und container: true in seiner Spezifikation haben * Duplikate werden abgelehnt

JSON-Ausgabe:

bausteinsicht add element --id newservice --kind service --title "New Service" --format json
# → {"id": "newservice", "kind": "service", "title": "New Service"}

bausteinsicht add relationship

Beziehung zwischen zwei bestehenden Elementen hinzufügen:

bausteinsicht add relationship \
  --from shop.api \
  --to paymentservice \
  --label "charge(amount)" \
  --kind rest \
  --description "Initiiert Zahlung"

Validierungen: * --from und --to müssen im Modell existieren * --kind muss in specification.relationships definiert sein (falls angegeben) * Duplikate (gleiche from/to/kind-Kombination) werden abgelehnt

bausteinsicht add view

Neue View erstellen oder bestehende View um Elemente erweitern:

# Neue View mit Scope
bausteinsicht add view payment-view \
  --title "Payment System" \
  --scope paymentservice \
  --include "paymentservice.*"

# Bestehende View um Element erweitern
bausteinsicht add view payment-view \
  --include shop.api

--include akzeptiert Element-IDs und Wildcards wie paymentservice.* (alle direkten Children).

bausteinsicht add-from-pattern

Patterns sind wiederverwendbare Element-Topologien in specification.patterns. Sie werden mit add-from-pattern instanziiert:

# Pattern "microservice" mit ID "notificationservice" instanziieren
bausteinsicht add-from-pattern microservice \
  --id notificationservice \
  --title "Notification Service"

# Mit Namespace-Präfix
bausteinsicht add-from-pattern microservice \
  --id emailworker \
  --prefix notification
# → erstellt "notification-emailworker" als Top-Level-ID

Das Pattern expandiert alle definierten Elemente und Beziehungen auf einmal.

Pattern auflisten

bausteinsicht add pattern list

Zeigt alle in specification.patterns definierten Patterns mit Element- und Beziehungsanzahl.

bausteinsicht add specification

Neue Typen zur Spezifikation hinzufügen:

# Neuen Element-Typ definieren
bausteinsicht add specification element \
  --kind "cache" \
  --notation "Cylinder" \
  --description "In-Memory Cache"

# Neuen Beziehungstyp definieren
bausteinsicht add specification relationship \
  --kind "event" \
  --notation "Event" \
  --dashed

Kommentare bleiben erhalten

Alle add-Befehle verwenden einen Comment-Preserving-Patcher: JSONC-Kommentare in architecture.jsonc werden nicht entfernt. Neue Einträge werden präzise an der richtigen Stelle eingefügt — ohne die bestehende Formatierung zu zerstören.

Falls der Patch fehlschlägt (z.B. bei komplexer Formatierung), fällt Bausteinsicht auf einen vollständigen Save zurück — der Inhalt ist dann korrekt, aber Kommentare könnten verloren gehen.

Nach jedem add-Befehl empfiehlt sich ein bausteinsicht sync damit das neue Element im draw.io-Diagramm erscheint.

Typischer Workflow per CLI

# 1. Neues Element hinzufügen
bausteinsicht add element --id cacheservice --kind cache --title "Redis Cache" --technology Redis

# 2. Beziehung hinzufügen
bausteinsicht add relationship --from shop.api --to cacheservice --label "read/write" --kind tcp

# 3. In bestehende View aufnehmen
bausteinsicht add view system-overview --include cacheservice

# 4. Sync: draw.io aktualisieren
bausteinsicht sync

# 5. Validieren
bausteinsicht validate

Beispiel-Modell

Das Beispiel für diesen Teil (per CLI schrittweise aufgebautes Modell) liegt unter teil_18.jsonc.

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

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

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

payment
system-overview

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Diagram
Diagram

Was als nächstes kommt

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org