Teil 25: Migration — Von draw.io, PlantUML und Structurizr zu Bausteinsicht

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: Tool Was ist da Aufwand 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: 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 DSL Bausteinsicht 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: Eine View migrieren — die wichtigste System-Context-View bausteinsicht sync und validate — prüfen dass das Modell konsistent ist Im Parallelbetrieb arbeiten — Bausteinsicht-Modell und altes Tool parallel pflegen bis das neue stabil ist 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: Generierte PlantUML-Diagramme via bausteinsicht export-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