Dieser Post setzt den vierundzwanzigsten Teil fort. In den meisten Projekten gibt es schon Architekturdokumentation — als draw.io-Datei im Wiki, als PlantUML im Repository oder als Structurizr-DSL. Migration bedeutet nicht: alles wegwerfen. Es bedeutet: den richtigen Anfang finden.

Die Ausgangslage verstehen

Bevor man migriert, lohnt sich eine ehrliche Bestandsaufnahme:

ToolWas ist daAufwand

Native draw.io (kein Modell dahinter)

Nur Diagramme, kein Datenmodell — die Elemente existieren nur als Shapes

Hoch: Modell muss von Grund auf aufgebaut werden

PlantUML C4

Strukturiertes Textmodell — Typen, Elemente, Beziehungen sind explizit

Mittel: Import-Script oder manueller Transfer möglich

Structurizr DSL

Vollständiges Modell mit Elementen, Beziehungen, Views

Mittel: strukturell ähnlich zu Bausteinsicht JSONC

Confluence-Diagramme / Powerpoint

Nur Bilder, kein maschinenlesbares Modell

Sehr hoch: Neuerstellen empfohlen

Schritt 1: Bausteinsicht init als Startpunkt

Unabhängig vom Ausgangstool immer zuerst:

mkdir architecture && cd architecture
bausteinsicht init

init erstellt ein Beispielmodell mit korrekter Grundstruktur — specification, model, views — und eine leere architecture.drawio. Das gibt einem die richtige Ausgangsbasis ohne von vorne anzufangen.

Dann: das generierte Beispielmodell löschen (aber specification.elements und specification.relationships als Vorlage behalten) und das eigene Modell aufbauen.

Von draw.io migrieren

Draw.io ohne Modell dahinter ist das häufigste Szenario. Der Ansatz: das bestehende Diagramm als visuelle Referenz nehmen, das JSONC-Modell davon ableiten.

Schritt 1: Bestehende draw.io-Datei öffnen, alle vorhandenen Elementtypen und Beziehungsarten identifizieren.

Schritt 2: Diese Typen in specification überführen:

{
  "specification": {
    "elements": {
      "system":     { "notation": "Software System", "container": true },
      "service":    { "notation": "Service" },
      "database":   { "notation": "Database" },
      "frontend":   { "notation": "Frontend" },
      "external":   { "notation": "External System" }
    },
    "relationships": {
      "uses":       { "notation": "uses" },
      "stores":     { "notation": "stores data in" },
      "calls":      { "notation": "calls" }
    }
  }
}

Schritt 3: Elemente und Beziehungen aus dem Diagramm in model überführen:

{
  "model": {
    "shop": {
      "kind": "system", "title": "Online Shop",
      "children": {
        "shop-api":      { "kind": "service",   "title": "Shop API",   "technology": "Go" },
        "shop-frontend": { "kind": "frontend",  "title": "Frontend",   "technology": "React" },
        "shop-db":       { "kind": "database",  "title": "Database",   "technology": "PostgreSQL" }
      }
    },
    "payment": { "kind": "external", "title": "Stripe" }
  }
}

Schritt 4: Views definieren die ungefähr den bestehenden Diagramm-Seiten entsprechen.

Schritt 5: bausteinsicht sync — Bausteinsicht erstellt draw.io-Shapes für alle Elemente. Dann Positionen aus dem Originaldiagramm manuell übertragen. Das ist Handarbeit, aber einmalig.

Nicht versuchen, das Originallayout pixelgenau zu rekonstruieren. Auto-Layout (→ Teil 14) danach neu anwenden ist oft der schnellere Weg.

Von PlantUML C4 migrieren

PlantUML C4 hat bereits ein strukturiertes Modell. Der Transfer ist mechanisch:

Diagram

Wird zu:

{
  "specification": {
    "elements": {
      "person":   { "notation": "Person" },
      "system":   { "notation": "Software System", "container": true },
      "external": { "notation": "External System" }
    },
    "relationships": {
      "uses": { "notation": "uses" }
    }
  },
  "model": {
    "user":    { "kind": "person",   "title": "Benutzer" },
    "shop":    { "kind": "system",   "title": "Online Shop" },
    "payment": { "kind": "external", "title": "Stripe" }
  }
}

Für größere Modelle lohnt sich ein kleines Konvertier-Script (Python, awk) das die System(…​) und Rel(…​) Aufrufe parst und JSONC-Fragmente ausgibt.

Von Structurizr DSL migrieren

Structurizr DSL ist strukturell am nächsten an Bausteinsicht JSONC. Die Konzepte sind direkt übertragbar:

Structurizr DSLBausteinsicht JSONC

softwareSystem "Name"

{ "kind": "system", "title": "Name" }

container "Name" "Description" "Technology"

{ "kind": "container", "title": "Name", "technology": "Technology", "description": "Description" }

relationship → target "Label"

{ "from": "source", "to": "target", "kind": "uses", "title": "Label" }

systemContext view { include * }

{ "include": ["*"] } in Views

styles { element "System" { …​ } }

specification.elements.system.style: { …​ }

Das Haupt-Delta: Structurizr unterstützt implizite Elemente in Views (include *), Bausteinsicht arbeitet mit expliziten IDs oder Tags.

View-by-View-Strategie statt Big Bang

Der häufigste Fehler bei Migration: versuchen alles auf einmal zu überführen.

Besser:

  1. Eine View migrieren — die wichtigste System-Context-View

  2. bausteinsicht sync und validate — prüfen dass das Modell konsistent ist

  3. Im Parallelbetrieb arbeiten — Bausteinsicht-Modell und altes Tool parallel pflegen bis das neue stabil ist

  4. Nächste View migrieren — schrittweise, nach Priorität

Das kostet mehr Zeit über die gesamte Migration, aber minimiert das Risiko: zu jedem Zeitpunkt gibt es eine funktionierende Dokumentation.

Fallstricke

Relationship Lifting: Bausteinsicht hebt Beziehungen automatisch auf das nächste sichtbare Elternelement an (→ Teil 3). In PlantUML oder draw.io gibt es das nicht — Beziehungen die im Originaltool explizit eingetragen waren, erscheinen in Bausteinsicht in einer abstrakteren View eventuell zusammengefasst. Das ist kein Bug, sondern Feature — aber man muss es bei der Überprüfung kennen.

Fehlende Typdefinitionen: Wenn das Originaltool keine Typen erzwingt (draw.io), ist die specification schnell unvollständig. validate hilft dabei alle verwendeten aber undeklarierten Typen zu finden.

IDs sind stabil, Titel nicht: In Bausteinsicht ist die Element-ID der stabile Schlüssel. Titel können geändert werden. In Migrationen aus Tools ohne IDs (draw.io) muss man IDs bewusst vergeben — und sie dann konsequent beibehalten.

Beispiel-Modell

Das Beispiel für diesen Teil (aus Structurizr/draw.io migriertes Modell mit Legacy-ERP-Anbindung) liegt unter teil_25.jsonc.

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

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

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

containers
context

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Diagram
Diagram

Weiter geht es mit Team-Workflows

Eine Migration ist selten ein Solo-Projekt. Im nächsten Teil geht es darum wie mehrere Personen gleichzeitig am Modell arbeiten — Merge-Konflikte in JSONC, Ownership-Conventions und der Review-Prozess für Architekturänderungen.

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org