Dieser Post setzt den fünfzehnten Teil fort. In größeren Organisationen pflegt jedes Team sein eigenes Architekturmodell. Der Workspace kombiniert mehrere Modelle zu einer übergreifenden Sicht — ohne die Team-Autonomie aufzugeben.

Das Problem: Teamgrenzen im Architekturmodell

Team A besitzt shop-model/architecture.jsonc, Team B auth-model/architecture.jsonc. Beide wollen ihre Modelle unabhängig pflegen — aber die Plattformarchitektur braucht eine Gesamtsicht.

Der Workspace ist die Antwort: eine workspace.jsonc referenziert beide Modelle und definiert die Verbindungen zwischen ihnen.

workspace.jsonc

{
  "workspace": {
    "name": "E-Commerce Platform",
    "description": "Gesamtarchitektur aller Teams"
  },
  "models": [
    {
      "id":     "shop",
      "path":   "teams/shop/architecture.jsonc",
      "prefix": "shop"
    },
    {
      "id":     "auth",
      "path":   "teams/auth/architecture.jsonc",
      "prefix": "auth"
    },
    {
      "id":     "payment",
      "path":   "teams/payment/architecture.jsonc",
      "prefix": "payment"
    }
  ],
  "crossModelRelationships": [
    {
      "id":    "shop-uses-auth",
      "from":  "shop.api",
      "to":    "auth.service",
      "label": "authenticate",
      "kind":  "rest"
    },
    {
      "id":    "shop-uses-payment",
      "from":  "shop.checkout",
      "to":    "payment.gateway",
      "label": "charge",
      "kind":  "rest"
    }
  ],
  "views": {
    "platform-overview": {
      "title":       "Platform-Übersicht",
      "include-from": ["shop", "auth", "payment"],
      "description": "Alle Teams, nur Top-Level-Elemente"
    },
    "checkout-flow": {
      "title":       "Checkout-Flow",
      "include-from": ["shop", "payment"],
      "include-kinds": ["service", "database"]
    }
  }
}

Element-Präfix

Das prefix-Feld verhindert ID-Kollisionen beim Merge: api aus dem Shop-Modell wird zu shop.api, service aus dem Auth-Modell zu auth.service.

Ohne expliziten prefix wird die id des Modells als Präfix verwendet.

bausteinsicht workspace list

Modelle im Workspace anzeigen:

bausteinsicht workspace list workspace.jsonc

Ausgabe:

Workspace: E-Commerce Platform
Description: Gesamtarchitektur aller Teams

Models:
  1. ID: shop, Path: teams/shop/architecture.jsonc, Prefix: shop
  2. ID: auth, Path: teams/auth/architecture.jsonc, Prefix: auth
  3. ID: payment, Path: teams/payment/architecture.jsonc, Prefix: payment

Cross-Model Relationships: 2
Workspace Views: 2

bausteinsicht workspace validate

Alle referenzierten Modelle laden und validieren:

bausteinsicht workspace validate workspace.jsonc

Prüft: * Alle Modell-Pfade existieren und sind valide JSONC * Jedes einzelne Modell besteht bausteinsicht validate * Cross-Model-Referenzen zeigen auf existierende (präfixierte) Elemente

Bei Erfolg:

✓ Workspace configuration is valid (3 models)

JSON-Ausgabe für CI:

bausteinsicht workspace validate workspace.jsonc --format json
# → {"valid": true, "models": 3}

bausteinsicht workspace merge

Alle Modelle zu einem einzigen zusammengeführten Modell vereinen:

bausteinsicht workspace merge workspace.jsonc merged-architecture.jsonc

Das resultierende merged-architecture.jsonc:

  • Enthält alle Elemente aller Teams mit Präfix-IDs

  • Enthält alle Cross-Model-Relationships

  • Besteht bausteinsicht validate

Das Merged-Modell kann dann für Exports, Graph-Analyse oder Overlay-Visualisierung verwendet werden:

bausteinsicht workspace merge workspace.jsonc /tmp/merged.jsonc

# Graph-Analyse auf Gesamtarchitektur
bausteinsicht graph --model /tmp/merged.jsonc

# Overlay auf Gesamtdiagramm
bausteinsicht overlay apply metrics.json --model /tmp/merged.jsonc --metric error_rate

Typische Workspace-Struktur im Repository

architecture/
├── workspace.jsonc          ← Workspace-Konfiguration
├── teams/
│   ├── shop/
│   │   ├── architecture.jsonc
│   │   └── architecture.drawio
│   ├── auth/
│   │   ├── architecture.jsonc
│   │   └── architecture.drawio
│   └── payment/
│       ├── architecture.jsonc
│       └── architecture.drawio
└── merged/
    └── architecture.jsonc   ← Generiert, nicht manuell editieren
Das merged/-Verzeichnis in .gitignore aufnehmen oder als Build-Artefakt behandeln — es wird aus den Team-Modellen regeneriert und soll nicht direkt bearbeitet werden.

CI: Workspace-Validierung

- name: Validate workspace
  run: bausteinsicht workspace validate architecture/workspace.jsonc

- name: Merge and analyze
  run: |
    bausteinsicht workspace merge architecture/workspace.jsonc /tmp/merged.jsonc
    bausteinsicht graph --model /tmp/merged.jsonc --cycles-only

Beispiel-Modell

Das Beispiel für diesen Teil (Team-Modell "shop" — eines von mehreren Modellen im Workspace) liegt unter teil_16.jsonc.

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

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