> For the complete documentation index, see [llms.txt](https://prof.aheil.de/seks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prof.aheil.de/seks/c4.md). # C4 Software Dokumentation ## ## Lernziele **Probleme** bei der Dokumentation von Software-Architekturen **verstehen** Die **vier Ebenen** des C4-Models **kennen** Das C4 Modell auf Problemstellungen **anwenden können** Software-Architekturen mit Hilfe des C4-Models **dokumentieren und kommunizieren können** ## Probleme bei der Dokumentation Welches ist die beste/einfachste/verständlichste Art Software-Architekturen zu dokumentieren So? Schnell und einfach aber klar und verständlich?

Besser so? Formal ja, aber genügend Detailgrad und unmißverständlich?

Noch besser so? Formal ja, mehr Detailgrad, aber genug Implementierungsetails? Was bedeuten die Pfeile?

Oder seher so? Autoamtisiert ja, aber klar und verständlich?

Vielleicht aber doch so:

Twitter Architektur Zeichnung von Elon Musk, annotiert von Justin Hendrix, Luke Dubois and Mark Hansen. Original Miro board: https://miro.com/app/board/uXjVPBnTJmM=/

Ganz oft dann aber auch so, weil einfach und handhabbar und nicht formal:

**Problem formaler Methoden**: Diese sind "synthetisch" und müssen gelernt werden. Sie müssen von beiden Seiten verstande n werden. Daher einigt man ich meistens pragmatisch auf die Ebene, die beide Seiten verstehen. ## Motivation Visuelle Kommunikation im Baugewerbe: Hier gibt es Lageplane, Raumpläne, Bebauungspläne, Querschnittsansichten, detaillierte Standardzeichnungen und technische Zeichnungen, die von den ausführenden Gewerken in der Regel ohne Probleme gelsen und (fehlerfrei) umgesetzt werden können.

Wie sieht hingegen die Kommunikation in Software-Projekten aus?

* Durcheinander von Boxen und Linien * Inkonsistente Notationen, Farben, Formen und Linien * Mehrdeutige Bezeichnungen * Beziehungen nicht benannt * Fehlende Technologieentscheidungen und Details * Vermischte Abstraktionslevel Aufgrund der Bewegung hin zu agilen Methoden wird weniger "Up Front Design" durchgeführt und es finden sich weniger Software-Diagramme in agilen Projekten. Wenn Diagramme genutzt werden sind diese oftmals * Unklar * Mehrdeutig * Verwirrend * und haben vermischte Detailgrade ## C4 Modell Das [C4 Modell](https://c4model.com) nutzt so.g Code-Landkarten zum verschiedene Sichten (Detaillevel) auf eine Software-Architektur zu modellieren. Jede Sicht kann für einen ganz unterschiedlichen Zweck und eine unterschiedliche Zielgruppe genutzt werden. **Context**

In welchem Gesamtkontext befindet sich das System, an welche externen Systeme grenzt es an? Das Kontextdiagram beschreibt das Big Picture. Wie passen die Teile in den Gesamtkontext? **Container**

Aus welchen Bestandeilen besteht das System. Im C4 Model sind hierbei Einheiten beschrieben, die Code hosten. Es kann sich dabei z.B. um auch einen Appliation Server handeln. **Component**

Wie sind die einzelnen Bestandteile aufgebaut. In der Regel sind dies Gruppen von zusammengehörigen Funktionen, die hinter einer wohldefinierten Schnittstelle verborgen sind. **Code**

Bildquelle Peter Schmelzle - Self-photographed, CC BY-SA 3.0

Wie sehen die Bestandtiel des Systems im Detil aus. Hier werden Klassen, Schnittstelle, Objekte, Funktionen, Tabellen etc. innerhalb einer Komponente beschrieben. Das C4 Model ist gedacht, um Software-Architekturen zu modellieren und zu kommunizieren. Es unterstützt einen “Abstraction First“ Ansatz und reflektiert die Denkweise von Entwicklern und Software-Architekten Es ist auch geeignet um Architekturen “Up Front” oder im Nachhinein zu dokumentieren. ## C4 Metamodell

## Level 1: System Context Diagram * Scope: Ein einzelnes Software System Primäre * Elemente: Das im Scope befindliche Software System Unterstützende * Elemente: Personen und Software Systeme, die direkt mit dem im Scope befindlichen Software System in Verbindung * Zielgruppe: Technische und nicht-technische Personen innerhalb und außerhalb des Entwicklungs-Teams

## Level 2: Container Diagram * Scope: Ein einzelnes Software System Primäre * Elemente: Der im Scope befindliche Container Unterstützende Elemente: Personen und Software System, die mit dem im Scope befindlichen Container in Verbindung stehen * Zielgruppe: Technische Personen innerhalb und außerhalb des Software Entwicklungs-Teams; einschließlich Software Architekten, Entwickler und Betriebs- und Supportpersonal # * Hinweis: Container Diagramme treffen keine Aussage über die Deployment Szenarien, eventuelles Clustering, Replikations- und/oder Failover-Szenarien etc.

## Level 3: Component Diagram * Scope: Ein einzelner Container Primäre Elemente: Komponenten innerhalbs des im Scope befindlichen Containers Unterstützende * Elemente: Containers (innerhalb des im Scope befindlichen Software Systems) + Personen und Software Systeme, die direkt mit den Komponenten in Verbindung stehen * Zielgruppe: Software Architekten and Entwickler

## Level 4 Code Diagram * Scope: Eine einzelne Komponente Primäre Elemente: Code * Elemente (z.B. Klassen, Interfaces, Objekte, Methoden und Funktionen, Datenbanken und Tabellen etc.) innerhalb der im Scope befindlichen Komponente * Zielgruppe: Software-Architekten und Entwickler

## Zusätzliche Diagramme Die 4 Level sind nicht immer ausreichend Wo nötig mit Komplementären ergänzen. Beispiele hierfür sind: * Systemlandschaft: In der echten Welt sind Software Systeme schon lange nicht mehr voneinander isolier und zeigen z.B. wie Systeme innerhalb eines Unternehmen zusammenspielen * Dynamische Diagramme: UML Kollaborationsdiagramme, UML Sequenzdiagamme * Deployment Diagramme: UML Deployment Diagramme einschließlich Containers and Deployment Nodes ## Praxisbeispiel

Quelle: https://docs.microsoft.com/en-us/azure/architecture/reference-architectures/app-service-web-app/scalable-web-app

Anhand der Microsoft Referenz Architektur für Microsoft Azure App Service ist es schwer, die exkaten Komponenten und das Zusammenspiel der Systembestandteile zu verstehen und letztendlich umzusetzen. Anhand eines Level 2 Diagrams lässt sich dies wesentlich klarer ausdrücken: