Teil 29: Real-Life-Beispiel — Structurizr Big Bank mit bausteinsicht import

Dieser Post baut auf dem achtundzwanzigsten Teil auf. Alle bisherigen Beispiele im Tutorial zeigten fiktive Systeme. Hier kommt ein echtes Referenzmodell: das Big Bank Example von Simon Brown — dem Erfinder des C4-Modells und Hauptentwickler von Structurizr. Und zum ersten Mal wird es nicht von Hand geschrieben, sondern direkt aus Structurizr DSL importiert. bausteinsicht import --from structurizr ist ab dem Release nach v1.1.0 verfügbar (gemergt in PR #331). Mit der aktuell installierten v1.1.0 funktioniert der Befehl noch nicht — wer es schon jetzt ausprobieren will, baut Bausteinsicht lokal aus main. Was ist das Big Bank Example? Das Big Bank Example ist das offizielle Referenzmodell der Structurizr-Dokumentation. Es zeigt eine fiktive Retail-Bank mit einem Internet Banking System auf drei C4-Ebenen: System Context — Kunden, Bankmitarbeiter, ATM, externe Systeme Container — Web App, SPA, Mobile App, API Application, Oracle-Datenbank Component — Sechs Komponenten der API Application Das Modell ist komplex genug um alle Features von Bausteinsicht zu zeigen, und bekannt genug um es sofort einordnen zu können. Original in Structurizr DSL: https://structurizr.connectedpdf.com/share/3/dsl Structurizr Container-Diagramm live: https://structurizr.com/embed/39258?diagram=Containers&diagramSelector=false Voraussetzungen # Bausteinsicht aus main (solange v1.2.0 noch nicht released): go install github.com/docToolchain/Bausteinsicht/cmd/bausteinsicht@main # Oder bei installiertem Node.js: npm install -g @doctoolchain/bausteinsicht@next Ein leeres Verzeichnis für das Experiment: mkdir bigbank && cd bigbank Schritt 1: DSL herunterladen Das kombinierte Big Bank DSL (System Landscape + Internet Banking System) direkt von Structurizr holen: curl -o bigbank.dsl https://structurizr.connectedpdf.com/share/3/dsl workspace "Big Bank plc" "This is an example workspace..." { model { customer = person "Personal Banking Customer" "..." enterprise "Big Bank plc" { supportStaff = person "Customer Service Staff" "..." backoffice = person "Back Office Staff" "..." mainframe = softwaresystem "Mainframe Banking System" "..." "Existing System" email = softwaresystem "E-mail System" "..." "Existing System" atm = softwaresystem "ATM" "..." "Existing System" internetBankingSystem = softwaresystem "Internet Banking System" "..." { webApplication = container "Web Application" "..." "Java and Spring MVC" spa = container "Single-Page Application" "..." "JavaScript and Angular" mobileApp = container "Mobile App" "..." "Xamarin" apiApplication = container "API Application" "..." "Java and Spring MVC" { signinController = component "Sign In Controller" "..." "Spring MVC" accountsSummaryController = component "Accounts Summary Controller" "..." "Spring MVC" resetPasswordController = component "Reset Password Controller" "..." "Spring MVC" securityComponent = component "Security Component" "..." "Spring Bean" mainframeBankingSystemFacade = component "Mainframe Banking System Facade" "..." "Spring Bean" emailComponent = component "E-mail Component" "..." "Spring Bean" } database = container "Database" "..." "Oracle Database Schema" } } customer -> internetBankingSystem "Views account balances, and makes payments using" customer -> supportStaff "Asks questions to" "Telephone" customer -> atm "Withdraws cash using" ... } } Schritt 2: Vorschau mit --dry-run Bevor eine Datei geschrieben wird, den Import als Vorschau ausführen: bausteinsicht import --from structurizr bigbank.dsl --dry-run Der Befehl gibt das generierte JSONC auf stdout aus — ohne etwas zu schreiben. So lässt sich prüfen ob das Parsing korrekt ist, bevor man eine vorhandene architecture.jsonc überschreibt. { "$schema": "https://raw.githubusercontent.com/docToolchain/Bausteinsicht/main/schemas/bausteinsicht.schema.json", "specification": { "elements": { "person": { "notation": "Person" }, "system": { "notation": "Software System", "container": true }, "container": { "notation": "Container", "container": true }, "component": { "notation": "Component", "container": true } }, "relationships": { "uses": { "notation": "uses" } }, "tags": [ { "id": "existing-system" }, { "id": "bank-staff" }, { "id": "web-browser" }, { "id": "mobile-app" }, { "id": "database" } ] }, "model": { ... }, "relationships": [ ... ], "views": { ... } } Falls das Parsing eines bestimmten DSL-Konstrukts nicht unterstützt wird, gibt bausteinsicht import eine Warnung auf stderr aus — der Import läuft aber weiter durch. Deployment-Diagramme (deploymentEnvironment) werden übersprungen und als Warnung gemeldet. Schritt 3: Import ausführen bausteinsicht import --from structurizr bigbank.dsl Ergebnis: ✓ Parsed 3 persons, 4 systems, 5 containers, 6 components ✓ Resolved 25 relationships ⚠ Skipped: deploymentEnvironment "Development" (not supported) ⚠ Skipped: deploymentEnvironment "Live" (not supported) ✓ Written architecture.jsonc architecture.jsonc liegt jetzt im Verzeichnis. Das generierte File für das Big Bank Example siehst du hier: { // Teil 29: Big Bank Example — transformiert von Structurizr DSL nach Bausteinsicht JSONC // Original DSL: https://structurizr.connectedpdf.com/share/3/dsl // Quelle: Simon Brown, Big Bank plc (kombiniert aus workspace 28201 + 36141) "$schema": "https://raw.githubusercontent.com/docToolchain/Bausteinsicht/main/schemas/bausteinsicht.schema.json", "config": { "author": "Simon Brown (Original), Paul Fleischmann (Bausteinsicht-Transformation)", "metadata": true, "legend": true }, "specification": { "elements": { "actor": { "notation": "Person" }, "system": { "notation": "Software System", "container": true }, "container": { "notation": "Container", "container": true }, "component": { "notation": "Component", "container": true } }, "relationships": { "uses": { "notation": "uses" }, "sends": { "notation": "sends", "dashed": true } }, "tags": [ { "id": "external", "description": "Existing System — nicht unter unserer Kontrolle", "style": { "fillColor": "#999999", "fontColor": "#ffffff" } }, { "id": "bank-staff", "description": "Bankmitarbeiter (intern)", "style": { "fillColor": "#08427b", "fontColor": "#ffffff" } }, { "id": "web-browser", "description": "Läuft im Web-Browser des Kunden" }, { "id": "mobile", "description": "Läuft auf dem Mobilgerät des Kunden" }, { "id": "database", "description": "Datenbank" } ] }, "model": { // ── Personen ───────────────────────────────────────────────────────────── "customer": { "kind": "actor", "title": "Personal Banking Customer", "description": "A customer of the bank, with personal bank accounts." }, "support-staff": { "kind": "actor", "title": "Customer Service Staff", "description": "Customer service staff within the bank.", "tags": ["bank-staff"] }, "backoffice": { "kind": "actor", "title": "Back Office Staff", "description": "Administration and support staff within the bank.", "tags": ["bank-staff"] }, // ── Externe Systeme ─────────────────────────────────────────────────────── "mainframe": { "kind": "system", "title": "Mainframe Banking System", "description": "Stores all of the core banking information about customers, accounts, transactions, etc.", "tags": ["external"] }, "email": { "kind": "system", "title": "E-mail System", "description": "The internal Microsoft Exchange e-mail system.", "tags": ["external"] }, "atm": { "kind": "system", "title": "ATM", "description": "Allows customers to withdraw cash.", "tags": ["external"] }, // ── Internet Banking System (intern, mit Containern) ────────────────────── "internet-banking": { "kind": "system", "title": "Internet Banking System", "description": "Allows customers to view information about their bank accounts, and make payments.", "status": "deployed", "children": { "web-app": { "kind": "container", "title": "Web Application", "technology": "Java and Spring MVC", "description": "Delivers the static content and the Internet banking single page application.", "status": "deployed" }, "spa": { "kind": "container", "title": "Single-Page Application", "technology": "JavaScript and Angular", "description": "Provides all of the Internet banking functionality to customers via their web browser.", "status": "deployed", "tags": ["web-browser"] }, "mobile-app": { "kind": "container", "title": "Mobile App", "technology": "Xamarin", "description": "Provides a limited subset of the Internet banking functionality to customers via their mobile device.", "status": "deployed", "tags": ["mobile"] }, "api-app": { "kind": "container", "title": "API Application", "technology": "Java and Spring MVC", "description": "Provides Internet banking functionality via a JSON/HTTPS API.", "status": "deployed", "children": { "sign-in": { "kind": "component", "title": "Sign In Controller", "technology": "Spring MVC Rest Controller", "description": "Allows users to sign in to the Internet Banking System." }, "accounts-summary": { "kind": "component", "title": "Accounts Summary Controller", "technology": "Spring MVC Rest Controller", "description": "Provides customers with a summary of their bank accounts." }, "reset-password": { "kind": "component", "title": "Reset Password Controller", "technology": "Spring MVC Rest Controller", "description": "Allows users to reset their passwords with a single use URL." }, "security": { "kind": "component", "title": "Security Component", "technology": "Spring Bean", "description": "Provides functionality related to signing in, changing passwords, etc." }, "mainframe-facade": { "kind": "component", "title": "Mainframe Banking System Facade", "technology": "Spring Bean", "description": "A facade onto the mainframe banking system." }, "email-component": { "kind": "component", "title": "E-mail Component", "technology": "Spring Bean", "description": "Sends e-mails to users." } } }, "database": { "kind": "container", "title": "Database", "technology": "Oracle Database Schema", "description": "Stores user registration information, hashed authentication credentials, access logs, etc.", "status": "deployed", "tags": ["database"] } } } }, "relationships": [ // ── System Context ──────────────────────────────────────────────────────── { "from": "customer", "to": "internet-banking", "label": "views account balances, and makes payments using", "kind": "uses" }, { "from": "customer", "to": "support-staff", "label": "asks questions to", "kind": "uses" }, { "from": "customer", "to": "atm", "label": "withdraws cash using", "kind": "uses" }, { "from": "support-staff", "to": "mainframe", "label": "uses", "kind": "uses" }, { "from": "backoffice", "to": "mainframe", "label": "uses", "kind": "uses" }, { "from": "atm", "to": "mainframe", "label": "uses", "kind": "uses" }, { "from": "internet-banking", "to": "mainframe", "label": "gets account information from, and makes payments using", "kind": "uses" }, { "from": "internet-banking", "to": "email", "label": "sends e-mail using", "kind": "sends" }, { "from": "email", "to": "customer", "label": "sends e-mails to", "kind": "sends" }, // ── Container: Customer → Frontend ──────────────────────────────────────── { "from": "customer", "to": "internet-banking.web-app", "label": "visits bigbank.com/ib using [HTTPS]", "kind": "uses" }, { "from": "customer", "to": "internet-banking.spa", "label": "views account balances, and makes payments using", "kind": "uses" }, { "from": "customer", "to": "internet-banking.mobile-app", "label": "views account balances, and makes payments using", "kind": "uses" }, { "from": "internet-banking.web-app", "to": "internet-banking.spa", "label": "delivers to the customer's web browser", "kind": "uses" }, // ── Container: Frontend → Components ───────────────────────────────────── { "from": "internet-banking.spa", "to": "internet-banking.api-app.sign-in", "label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, { "from": "internet-banking.spa", "to": "internet-banking.api-app.accounts-summary","label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, { "from": "internet-banking.spa", "to": "internet-banking.api-app.reset-password", "label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, { "from": "internet-banking.mobile-app", "to": "internet-banking.api-app.sign-in", "label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, { "from": "internet-banking.mobile-app", "to": "internet-banking.api-app.accounts-summary","label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, { "from": "internet-banking.mobile-app", "to": "internet-banking.api-app.reset-password", "label": "makes API calls to [JSON/HTTPS]", "kind": "uses" }, // ── Component: intern ───────────────────────────────────────────────────── { "from": "internet-banking.api-app.sign-in", "to": "internet-banking.api-app.security", "label": "uses", "kind": "uses" }, { "from": "internet-banking.api-app.accounts-summary","to": "internet-banking.api-app.mainframe-facade","label": "uses", "kind": "uses" }, { "from": "internet-banking.api-app.reset-password", "to": "internet-banking.api-app.security", "label": "uses", "kind": "uses" }, { "from": "internet-banking.api-app.reset-password", "to": "internet-banking.api-app.email-component", "label": "uses", "kind": "uses" }, { "from": "internet-banking.api-app.security", "to": "internet-banking.database", "label": "reads from and writes to [JDBC]", "kind": "uses" }, { "from": "internet-banking.api-app.mainframe-facade","to": "mainframe", "label": "makes API calls to [XML/HTTPS]", "kind": "uses" }, { "from": "internet-banking.api-app.email-component", "to": "email", "label": "sends e-mail using", "kind": "sends" } ], "views": { "context": { "title": "System Context — Big Bank plc", "description": "Alle Akteure und Systeme rund um das Internet Banking System", "include": ["customer", "support-staff", "backoffice", "internet-banking", "mainframe", "email", "atm"] }, "containers": { "title": "Container — Internet Banking System", "description": "Interne Container des Internet Banking Systems und ihre Nachbarn", "scope": "internet-banking", "include": ["customer", "internet-banking.*", "mainframe", "email"] }, "components": { "title": "Component — API Application", "description": "Interne Komponenten der API Application", "scope": "internet-banking.api-app", "include": [ "internet-banking.spa", "internet-banking.mobile-app", "internet-banking.api-app.*", "internet-banking.database", "mainframe", "email" ] } } } Was der Importer automatisch macht Hierarchie erhalten — Structurizr-Blöcke ({ }) werden zu children-Objekten in JSONC. Der vollständig gepunktete Pfad (internet-banking.api-app.sign-in) wird aus den DSL-Variablennamen abgeleitet. Beziehungen auflösen — Structurizr erlaubt Beziehungen die vor der Element-Definition stehen (a → b). Der Importer löst alle Referenzen verzögert auf (deferred resolution) — das Ergebnis ist immer ein konsistentes JSONC. Tags übernehmen — Structurizr-Tags ("Existing System", "Bank Staff", "Web Browser") werden 1:1 in specification.tags übernommen und an die Elemente angehängt. Views konvertieren — systemContext, container und component Views werden in Bausteinsicht-Views übersetzt. include * wird in eine explizite include-Liste aufgelöst. Was nachzubessern ist Der Import ist ein Einmalvorgang — kein Mapping für alles. Folgendes muss manuell ergänzt werden: Nicht importiert Wie nachrüsten Deployment-Diagramme Separate Views in views anlegen oder in draw.io modellieren Styles / Themes specification.tags[].style mit draw.io-Farben befüllen !include-Direktiven Lokale Includes werden aufgelöst, HTTP-Includes nicht properties auf Containern metadata-Feld in Bausteinsicht verwenden Differenzierte Beziehungstypen Alle Beziehungen werden als uses importiert — sends, reads etc. manuell anpassen Das Wichtigste bei externen Systemen: Structurizr nutzt den String-Tag "Existing System". Der Importer übernimmt das als Tag existing-system. Für farbiges Styling in draw.io fügt man in specification.tags einfach eine style-Sektion ein: "specification": { "tags": [ { "id": "existing-system", "description": "Externes System — nicht unter unserer Kontrolle", "style": { "fillColor": "#999999", "fontColor": "#ffffff" } } ] } Schritt 4: Sync und Diagramme bausteinsicht sync Bausteinsicht generiert architecture.drawio mit drei Tabs: context — System Context: Kunden, Bankmitarbeiter, ATM, externe Systeme containers — Alle Container des Internet Banking Systems components — Sechs Komponenten der API Application Das draw.io-File dafür findest du hier: teil_29.drawio Generierte PNG-Dateien: Generierte PlantUML-Diagramme: Structurizr vs. Bausteinsicht — Kurzvergleich Aspekt Structurizr Bausteinsicht Modell-Format Eigene DSL JSONC Diagramm-Output SVG via Structurizr-Server draw.io (bearbeitbar, bidirektional) Bidirektional Nein — DSL ist Quelle der Wahrheit Ja — draw.io Änderungen fließen zurück ins JSONC Offline Structurizr Lite nötig Vollständig lokal Deployment-Diagramme Nativ in DSL Kein eingebautes Konzept Import aus Structurizr — bausteinsicht import --from structurizr Constraint-Prüfung !rules in DSL constraints im JSONC, bausteinsicht lint Die Migration in eine Richtung ist mit bausteinsicht import jetzt trivial. Zurück nach Structurizr gibt es keinen Importer — aber das ist in der Praxis selten nötig. Was als nächstes kommt Teil 30: Mehr Views aus einem Modell — wie man aus dem Big Bank Modell 7 fokussierte Diagramme für verschiedene Publikumsgruppen erzeugt Die wichtigsten Einstiegspunkte zum Nachschlagen: Neu starten? → Teil 2: Getting Started Architekturregeln? → Teil 8: Validation & Linting Mit KI arbeiten? → Teil 10: LLM/AI Workflows Team-Architektur? → Teil 16: Workspace Von anderen Tools? → Teil 25: Migration Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org