Was vorher fertig sein muss
Eine Liste der Container (Anwendungen, Datenbanken, Queues) des Systems mit Owner und Zweck liegt vor.
Bei DDD-Systemen liegen Canvases für die wichtigsten Contexts vor, sodass Container und Components fachliche Grenzen reflektieren.
Was vor Start vorliegen muss
Diagramm-Tool mit C4-Notation (Structurizr, IcePanel, Mermaid mit C4-Plugin, PlantUML mit C4-PlantUML, draw.io); Repo-Verzeichnis `docs/architecture/diagrams/`; Legende mit Notation (Person, Software System, Container, Component, Relationship).
Ein Architekt oder Tech Lead als Hauptverfasser; ein bis drei Engineers mit Implementierungswissen; optional Domain-Experten für Kontext-Diagramm; Reviewer aus Nachbarsystemen.
Aktuelle Liste der Container und Components; bekannte externe Systeme; Personas der Nutzer (Endnutzer, Operatoren, andere Systeme); Tech-Stack pro Container.
1-4 h
Diagramm-Tool aufsetzen, Notations-Konvention im Team abstimmen (Farben, Shapes, Pfeilrichtung). Source der Diagramme als Text-DSL im Repo, gerendert beim Build. Für jede Ebene eine eigene Datei.
Die eine Frage, die diese Methode beantwortet
Auf welcher Abstraktionsebene welcher Leser welche Architektur-Information aus dem Diagramm zieht?
Marker: Sektion
| Schritt | Dauer | Aktion | Hinweis |
|---|---|---|---|
1Sektion 1: System Context | 20-30 min | Das System in der Mitte als Box. Drumherum die Personen (Nutzer, Operatoren) und externen Software Systems mit denen es interagiert. Pro Beziehung Richtung und Zweck beschriften. | Maximal 7-10 Elemente. Mehr deutet darauf hin, dass externe Systeme zu fein gemappt werden oder das System nicht abgegrenzt ist. |
2Sektion 2: Container | 30-60 min | System aufzoomen. Container sind separate ausführbare Einheiten oder Datenspeicher (Web App, Mobile App, API Service, Database, Message Broker). Pro Container Technologie und Hauptverantwortlichkeit. | Container sind keine Klassen oder Module. Wenn etwas im selben Prozess läuft, ist es kein eigener Container. Anti-Pattern: Container für jede Klasse. |
3Sektion 3: Component (nur bei Bedarf) | 30-60 min | Für komplexe Container ein Component-Diagramm: logische Bausteine innerhalb des Containers (Controllers, Services, Repositories) mit Verantwortlichkeiten. | Nicht jeder Container braucht ein Component-Diagramm. Nur die mit echter interner Komplexität. Sonst veralten Diagramme schneller als der Code. |
4Sektion 4: Code (optional, selten) | 15-30 min | Bei kritischen Komponenten ein Code-Diagramm (UML-Klassen, Entitäten). Nur wenn Code-Struktur stark von Architekturentscheidungen abhängt. | Code-Ebene ist meist generierbar oder ohnehin im Code. Statisch gepflegt veraltert sie sofort. In 95% der Fälle weglassen. |
5Sektion 5: Legende und Konsistenz-Check | 10 min | Legende mit Notation, Farben und Bedeutungen pro Ebene. Cross-Check: Container im Context-Diagramm tauchen als Top-Level im Container-Diagramm auf, Components passen in ihren Container. | Inkonsistenz zwischen Ebenen ist der häufigste Lesefehler. Wenn Container A im Kontext erscheint, aber im Container-Diagramm fehlt, ist die Doku falsch. |
Was am Ende rauskommt
Verzeichnis mit System-Context-Diagramm, Container-Diagramm, Component-Diagrammen (pro relevantem Container) und Legende. Quelldateien als Text-DSL (Structurizr, PlantUML, Mermaid) im Repo, gerendert als PNG oder SVG für die Doku.
Diagrammquellen im Repo neben Code versioniert. Pro Release oder Major Change Snapshot. Diagramme im Pull Request mit verändertem Code reviewen. Rendered Outputs gehören in den Build, nicht ins Repo.
Kompakte Arbeitsvorlage für C4 Model mit Kontext, Input, Ergebnisartefakten und nächstem Schritt.
# C4 Model Canvas
## Kontext
Wofür wird die Methode eingesetzt?
## Kernfrage
Welche Frage soll am Ende beantwortet sein?
## Input
Welche Daten, Beobachtungen oder Materialien liegen vor?
## Arbeitsfläche
- Bereich 1:
- Bereich 2:
- Bereich 3:
- Beziehungen / Muster:
## Ergebnisartefakte
- Context Diagram:
- Container Diagram:
- Component Diagram:
## Offene Fragen
- ...
## Nächster Schritt
Owner, Datum, Erfolgssignal.Konkret gefülltes Szenario
## C4 — Order Platform (Stand: 2026-05-18)
### System Context
- **Order Platform** (System) interagiert mit:
- **Customer** (Person): bestellt über Web/Mobile
- **Operator** (Person): bearbeitet manuelle Eingriffe
- **Payment Gateway** (External System): Adyen, autorisiert Zahlungen via REST
- **Carrier API** (External System): DHL und DPD, REST für Versandlabels
- **Tax Service** (External System): internes Steuersystem, gRPC
### Container (Order Platform)
- **Web Frontend** (React, Next.js 16) — User Interaction
- **Mobile App** (React Native) — User Interaction
- **API Gateway** (Node.js, Fastify) — Authentication, Routing
- **Order Service** (Java 21, Spring Boot) — Order Lifecycle
- **Pricing Service** (Kotlin) — Preisberechnung
- **Order DB** (PostgreSQL 15) — Order State
- **Event Bus** (Kafka 3.6) — Asynchrone Integration
### Component (Order Service)
- **OrderController** (REST API) — empfängt Commands
- **OrderAggregate** (Domain) — Geschäftsregeln, Statusmaschine
- **OutboxPublisher** (Application) — schreibt Events transaktional in Outbox-Tabelle
- **OrderRepository** (Infrastructure) — Postgres-Zugriff via JPASymptome erkennen, gegensteuern
Container-Diagramm enthält Komponenten, die im selben Prozess laufen (z. B. Service-Klassen als Container).
Container-Definition strikt anwenden: separat deploybare Einheit oder Datenspeicher. Module innerhalb eines Prozesses gehören in Component-Ebene.
Diagramme nutzen Farben und Pfeilstile, ohne dass irgendwo erklärt ist was sie bedeuten.
Pro Diagrammseite Legende einblenden (Tool-Funktion oder manuell). Konvention im Team festlegen und konsistent anwenden.
Nur Bild-Dateien im Repo, keine Source-DSL. Änderung erfordert Reverse-Engineering oder Original-Tool.
Source als Text (Structurizr, PlantUML, Mermaid) im Repo. Rendering im CI. PNG-Output ist Build-Artefakt, nicht Source.
Jeder Container hat ein Component-Diagramm, auch triviale Wrapper-Services.
Component-Ebene nur für Container mit echter interner Komplexität (10+ relevante Bausteine). Sonst Aufwand-Nutzen-Verhältnis kippt.
Container im Diagramm existieren im Code nicht mehr, Beziehungen sind seit Monaten falsch.
Diagramm-Review als Definition of Done bei architekturrelevanten Änderungen. CI-Check: Beispiel-Linter prüft, ob Service-Namen aus Diagramm im Code existieren.
Klassen-Diagramme im Repo, die mit jedem Refactor neu gezeichnet werden müssen.
Code-Ebene generieren (z. B. mit jQAssistant, Code-to-UML) oder weglassen. Statisch gepflegt veraltet sie immer schneller als der Code.
Done-Signale, in unter einer Minute prüfbar
Zum Steckbrief für Zweck, ähnliche Methoden und Quellen — oder direkt zur nächsten Methode im Katalog.