Dieser Post setzt den zwanzigsten Teil fort. Architekturmigrationen sind komplex: man muss verstehen wo man gerade steht (As-Is) und wo man hin will (To-Be). Bausteinsicht unterstützt das direkt im Modell — als zwei parallele Snapshots.

Das Konzept

architecture.jsonc kann neben dem Hauptmodell zwei optionale Sektionen enthalten:

  • asIs — aktueller Zustand (Ist-Architektur)

  • toBe — Zielzustand (Soll-Architektur)

Beide haben die gleiche Struktur: elements und relationships.

{
  "model": { ... },

  "asIs": {
    "elements": {
      "shop-monolith": {
        "kind": "system",
        "title": "Shop Monolith",
        "technology": "Java/Spring"
      },
      "shop-db": {
        "kind": "database",
        "title": "Monolith DB",
        "technology": "MySQL"
      }
    },
    "relationships": [
      { "from": "shop-monolith", "to": "shop-db", "label": "reads/writes" }
    ]
  },

  "toBe": {
    "elements": {
      "shop-api": {
        "kind": "service",
        "title": "Shop API",
        "technology": "Go"
      },
      "auth-service": {
        "kind": "service",
        "title": "Auth Service",
        "technology": "Go"
      },
      "payment-service": {
        "kind": "service",
        "title": "Payment Service",
        "technology": "Rust"
      },
      "shop-db": {
        "kind": "database",
        "title": "Shop DB",
        "technology": "PostgreSQL"
      }
    },
    "relationships": [
      { "from": "shop-api",      "to": "auth-service",     "label": "authenticate" },
      { "from": "shop-api",      "to": "payment-service",  "label": "charge" },
      { "from": "shop-api",      "to": "shop-db",          "label": "reads/writes" },
      { "from": "payment-service","to": "shop-db",         "label": "audit" }
    ]
  }
}

bausteinsicht diff

diff vergleicht asIs mit toBe und gibt die Unterschiede aus:

bausteinsicht diff --model architecture.jsonc

Ausgabe:

Architecture Diff
=================

Added (3):
  + shop-api            [service ] "Shop API"
  + auth-service        [service ] "Auth Service"
  + payment-service     [service ] "Rust"

Removed (1):
  - shop-monolith       [system  ] "Shop Monolith"

Changed (1):
  ~ shop-db             [database]
      technology: "MySQL" → "PostgreSQL"

Added Relationships (3):
  + shop-api → auth-service (authenticate)
  + shop-api → payment-service (charge)
  + payment-service → shop-db (audit)

Removed Relationships (1):
  - shop-monolith → shop-db (reads/writes)

JSON-Ausgabe

bausteinsicht diff --model architecture.jsonc --format json

Gibt ein strukturiertes DiffResult-Objekt zurück mit summary (Zählungen) und elements-Array mit ChangeAdded, ChangeRemoved, ChangeChanged-Einträgen.

Nur eine View vergleichen

bausteinsicht diff --model architecture.jsonc --view shop-overview

Filtert den Diff auf Elemente die in der genannten View sichtbar sind.

Unterschied zu snapshot diff

Aspektbausteinsicht diffbausteinsicht snapshot diff

Vergleicht

asIs vs. toBe im gleichen Modell

Zwei Snapshots zu verschiedenen Zeitpunkten

Zweck

Migrationsplanung (Ziel definieren)

Rückblick (was hat sich verändert?)

Datenspeicherung

Im Modell selbst

In .bausteinsicht-snapshots/

Workflow: Migrationsplanung

  1. asIs mit dem aktuellen Systemzustand füllen

  2. toBe mit der Zielarchitektur füllen

  3. bausteinsicht diff — zeigt genau welche Schritte nötig sind

  4. Ergebnis in PR-Beschreibung oder ADR dokumentieren

  5. Nach der Migration: asIs auf toBe aktualisieren, toBe leeren oder nächste Migrationsstufe definieren

# Diff für PR-Beschreibung
bausteinsicht diff --model architecture.jsonc --format json \
  | jq '{ added: .summary.added_elements, removed: .summary.removed_elements, changed: .summary.changed_elements }'
asIs und toBe können auch schrittweise befüllt werden — für iterative Migrationen mit mehreren Zwischenzuständen. Zwischen den Sprints jeweils asIs aktualisieren wenn Elemente tatsächlich migriert wurden.

Beispiel-Modell

Das Beispiel für diesen Teil (Monolith → Microservices Migration mit asIs/toBe-Sektionen) liegt unter teil_21.jsonc.

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

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

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

containers
context

Generierte PlantUML-Diagramme via bausteinsicht export-diagram (aktuelle Migrationsphase):

Diagram
Diagram

Was als nächstes kommt

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org