Dieser Post setzt den sechsten Teil fort. Architecture-as-Code hat gegenüber manuellen Diagrammen einen entscheidenden Vorteil: die Architektur lebt im Git-Repository. Bausteinsicht nutzt das mit zwei Werkzeugen — snapshot und changelog.

Das Problem: Architekturdrift ohne Nachvollziehbarkeit

In agilen Projekten ändert sich die Architektur kontinuierlich. Nach sechs Monaten Entwicklung weiß oft niemand mehr: was wurde wann entschieden? Warum haben wir damals den Monolithen in Microservices aufgeteilt? Was ist zwischen Sprint 5 und Sprint 10 passiert?

Git löst das für Code. bausteinsicht snapshot und changelog lösen es für Architektur.

bausteinsicht snapshot

Snapshots sind benannte Momentaufnahmen des Architekturmodells, gespeichert in .bausteinsicht-snapshots/. Sie sind unabhängig von Git-Commits — ein Snapshot kann zu jedem Zeitpunkt gespeichert werden.

Snapshot speichern

# Einfacher Snapshot ohne Nachricht
bausteinsicht snapshot save

# Snapshot mit beschreibender Nachricht
bausteinsicht snapshot save --message "Sprint 5 Ende: Payment-Service extrahiert"

Ausgabe:

Snapshot saved: 20250611-143022
  Timestamp: 2025-06-11T14:30:22Z
  Elements:  12
  Relationships: 8
  Message: Sprint 5 Ende: Payment-Service extrahiert

Die ID ist ein Timestamp (YYYYMMDD-HHMMSS) — das erleichtert die zeitliche Zuordnung.

Snapshots auflisten

bausteinsicht snapshot list

Ausgabe:

ID               TIMESTAMP            ELEMENTS  RELATIONSHIPS  MESSAGE
20250301-090000  2025-03-01 09:00:00  5         3              Projekt-Start: Monolith
20250415-140000  2025-04-15 14:00:00  8         6              Sprint 3: Auth-Service
20250611-143022  2025-06-11 14:30:22  12        8              Sprint 5: Payment-Service

Als JSON für Scripting:

bausteinsicht snapshot list --format json

Snapshots vergleichen

Das eigentliche Feature: zwei Snapshots (oder einen Snapshot mit dem aktuellen Modell) vergleichen.

# Snapshot vs. aktuellen Zustand
bausteinsicht snapshot diff 20250301-090000

# Zwei Snapshots vergleichen
bausteinsicht snapshot diff 20250301-090000 20250611-143022

Ausgabe:

Architecture Differences (Total Changes: 9)
==================================================

Added Elements (4):
  + authservice
  + authservice.tokenstore
  + paymentservice
  + paymentservice.ledger

Removed Elements (1):
  - monolith

Changed Elements (2):
  ~ shop.api
      technology: "Go (monolith)" → "Go"
  ~ shop.db
      description: "" → "Primäre Datenbank für Orders und Products"

Added Relationships (3):
  + shop.frontend → authservice (authenticate)
  + shop.api → paymentservice (charge)
  + paymentservice → shop.db (audit log)

Removed Relationships (1):
  - shop.frontend → monolith (uses)

Als JSON für CI-Pipelines oder Weiterverarbeitung:

bausteinsicht snapshot diff 20250301-090000 --format json

Snapshot wiederherstellen

Ein Snapshot kann als JSONC-Datei exportiert werden — zum Inspizieren oder als Ausgangspunkt für einen neuen Branch:

# In eine neue Datei exportieren
bausteinsicht snapshot restore 20250301-090000 architecture-v1.jsonc

# Bestehende Datei überschreiben
bausteinsicht snapshot restore 20250301-090000 architecture.jsonc --force
restore überschreibt das aktuelle Modell. Vorher sicherstellen, dass der aktuelle Stand in Git committed ist oder als Snapshot gespeichert ist.

Snapshot löschen

bausteinsicht snapshot delete 20250301-090000

bausteinsicht changelog

changelog erzeugt einen lesbaren Architektur-Changelog aus der Git-History — ohne dass vorab Snapshots angelegt wurden.

Der Befehl liest das Modell an zwei verschiedenen Git-Refs (--since und --until) und berechnet den Unterschied.

Changelog seit dem letzten Tag

# Seit dem letzten Git-Tag bis HEAD
bausteinsicht changelog

# Explizite Referenzen
bausteinsicht changelog --since v1.0.0 --until HEAD

# Seit einem bestimmten Commit
bausteinsicht changelog --since abc1234 --until HEAD

# Nur den letzten Sprint (Branch-basiert)
bausteinsicht changelog --since origin/main --until feature/sprint-6

Ausgabeformate

# Markdown (Standard) — für GitHub PRs, README
bausteinsicht changelog --format markdown

# AsciiDoc — für technische Dokumentation
bausteinsicht changelog --format asciidoc --output docs/architecture-changelog.adoc

# JSON — für CI-Auswertung
bausteinsicht changelog --format json

Beispiel-Ausgabe (Markdown):

## Architecture Changelog

**From:** v1.0.0 (2025-03-01)
**To:** HEAD (2025-06-11)

### Added Elements (4)
- `authservice` — Auth Service
- `authservice.tokenstore` — Token Store
- `paymentservice` — Payment Service
- `paymentservice.ledger` — Ledger

### Removed Elements (1)
- `monolith` — Legacy Monolith

### Changed Elements (2)
- `shop.api`: technology changed from "Go (monolith)" to "Go"
- `shop.db`: description added

### Added Relationships (3)
- `shop.frontend` → `authservice` (authenticate)
- `shop.api` → `paymentservice` (charge)
- `paymentservice` → `shop.db` (audit log)

### Removed Relationships (1)
- `shop.frontend` → `monolith` (uses)

As-Is / To-Be Vergleich

Für geplante Migrationen bietet das Modell selbst einen Vergleichsmechanismus: die asIs- und toBe-Sektionen (→ Teil 3).

bausteinsicht diff visualisiert den Unterschied zwischen aktuellem Zustand (asIs) und Zielarchitektur (toBe) als annotiertes Diagramm:

bausteinsicht diff

Im draw.io-Diagramm erscheinen:

  • Neue Elemente (nur in toBe): grün markiert

  • Zu entfernende Elemente (nur in asIs): rot markiert

  • Unveränderte Elemente: normal

Das ist der Unterschied zu snapshot diff: snapshot diff vergleicht vergangene Zustände, diff visualisiert den geplanten Migrationspfad.

Praktischer Workflow in agilen Projekten

ZeitpunktAktion

Sprint-Start

bausteinsicht snapshot save --message "Sprint N Start"

Größere Architekturentscheidung

Modell ändern → commit → snapshot save --message "ADR-007: …​"

Sprint-Review

bausteinsicht snapshot diff <sprint-start-id> als Review-Input

Release

bausteinsicht changelog --since <letztes-release-tag> --format markdown → in Release Notes

Architektur-Review alle 3 Monate

bausteinsicht changelog --since <quartal-start> → für Review-Meeting

PR-Beschreibung

bausteinsicht changelog --since origin/main --until HEAD --format markdown

Snapshots und .bausteinsicht-sync gehören beide ins Git-Repository. So ist der vollständige Architekturverlauf in der Versionskontrolle — kein externes Werkzeug nötig.

Beispiel-Modell

Das Beispiel für diesen Teil (Sprint 5: Payment-Service extrahiert) liegt unter teil_7.jsonc.

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

Das draw.io-File dafür findest du hier: teil_7.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

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org