Architekturdiagramm erstellen: Schritt-für-Schritt-Anleitung für Softwareteams

Wenn du dein erstes Architekturdiagramm erstellst, ist das Schwierige nicht das Zeichnen der Kästen, sondern die Entscheidung, was du weglässt. In dieser Anleitung geht es um Diagramme für Software- und Systemarchitektur: Services, Datenbanken, Queues, Netzwerkzonen und die Verbindungen dazwischen. Egal ob es dein erstes Softwarearchitektur-Diagramm ist oder das zehnte deines Teams – mit den folgenden Schritten entsteht ein Diagramm, das man lesen kann und das aktuell bleibt.

Zuerst Leser und Frage festlegen

Ein gutes Diagramm beantwortet genau eine Frage. „Alles in unserem System“ ist keine Frage, sondern ein Inventar, und Inventare gehören in eine Tabelle.

Schreib vor dem ersten Strich zwei Sätze auf:

• Wer liest es? Eine neue Entwicklerin, der SRE in Rufbereitschaft, ein Security-Review, eine Produktmanagerin, ein externer Auditor.
• Welche Frage beantwortet es? „Durch welche Services läuft eine Bestellanfrage?“, „Was ist aus dem Internet erreichbar?“, „Wohin geht der Traffic, wenn eine Region ausfällt?“

Diese zwei Sätze legen den Umfang fest. Wer neu im Team ist, braucht einen anderen Detailgrad als das Netzwerkteam. Wenn du beide mit einem Bild bedienen willst, bedienst du keinen.

Den passenden Diagrammtyp wählen

Steht die Frage fest, ergibt sich der Typ fast von selbst. Das C4-Modell ist ein guter Ausgangspunkt: Es teilt ein System in die Zoomstufen Context, Container, Component und Code (Details auf c4model.com).

Wenn du unsicher bist, fang mit einem Context-Diagramm an. Es macht Systemgrenze und externe Abhängigkeiten sichtbar und gibt allen weiteren Diagrammen einen Rahmen.

Architekturdiagramm erstellen: Schritt für Schritt

1. Umfang und Grenze festlegen

Schreib auf, was im Diagramm liegt und was draußen bleibt. Komponenten, die deinem Team gehören, stehen innerhalb der Grenze; ein Payment-Provider, ein Identity-Provider oder der Service eines anderen Teams stehen außerhalb. Zeig jedes externe System als einen einzigen Kasten – dessen Innenleben musst du nicht zeichnen.

2. Komponenten auflisten

Mach vor dem Zeichnen eine Liste: Services, Datenbanken, Queues, Caches, externe APIs, Nutzertypen. Verwende die Namen, die das Team tatsächlich benutzt; noch besser, wenn sie zum Repo- oder Deployment-Namen passen. Ist die Liste zu lang, um sie auf einen Blick zu erfassen, hast du wahrscheinlich Stoff für zwei Diagramme.

3. Beziehungen als beschriftete, gerichtete Pfeile zeichnen

Eine unbeschriftete Linie sagt nur, dass zwei Dinge „irgendwie zusammenhängen“. Gib jedem Pfeil eine Richtung und mindestens zwei Angaben: Protokoll und Zweck. Ergänze sync oder async, wo es wichtig ist.

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

Der Pfeil zeigt vom Aufrufer zum Empfänger. Zeichne keinen zweiten Pfeil für die Antwort; das verdoppelt die Linien ohne Mehrwert. Wenn die Reihenfolge von Anfrage und Antwort zählt, ist das ein Fall für ein Sequenzdiagramm.

4. Mit Frames gruppieren

Gruppen sind die zweite Leseebene. Pack Komponenten in Grenzen, die etwas bedeuten:

• Netzwerkzonen: Public Subnet, Private Subnet, DMZ, On-Prem-Netz
• Kubernetes-Namespaces: payments, platform, observability
• Regionen und Accounts: eu-central-1, us-east-1, Prod- und Staging-Accounts
• Vertrauensgrenzen: wo Traffic aus dem Internet authentifiziert wird

Verschachteln ist in Ordnung (Region > VPC > Subnet), aber jede zusätzliche Ebene macht das Diagramm schwerer lesbar.

5. Eine Legende hinzufügen

Wenn Farbe, Linienart oder Icon etwas bedeuten, muss es in der Legende stehen. Ist eine gestrichelte Linie eine async-Nachricht? Ist ein roter Frame PCI-Scope? Was für dich beim Zeichnen offensichtlich ist, ist es für jemanden, der das Diagramm sechs Monate später liest, nicht mehr.

6. Titel, Datum und Owner ergänzen

Jedes Diagramm braucht in einer Ecke drei Angaben: einen Titel, der sagt, was es zeigt („Checkout – Container-Sicht, Prod“), das Datum der letzten Änderung und das verantwortliche Team. Bei einem Diagramm ohne Datum weiß niemand, ob es aktuell ist, und ein Diagramm ohne Owner aktualisiert niemand.

7. Mit jemandem reviewen, der es nicht gezeichnet hat

Zeig das Diagramm jemandem, der es nicht gezeichnet hat, und stell die Frage, die du am Anfang aufgeschrieben hast. Findet die Person die Antwort ohne deine Erklärung, funktioniert das Diagramm. Wenn du ständig sagst „hier meinte ich eigentlich …“, gehört diese Erklärung ins Diagramm.

Häufige Fehler

• Alles in ein Diagramm packen. Context, Deployment und Netzwerkdetails in einem Bild – am Ende liest niemand etwas davon.
• Unbeschriftete oder doppelseitige Pfeile. Wer wen aufruft, bleibt unklar – und genau das sucht man während eines Incidents.
• Gemischte Abstraktionsebenen. Ist ein Kasten „Payment-System“ und der nächste „Redis-Pod“, verliert der Leser den Maßstab.
• Unerklärte Farben. Farben, die nicht in der Legende stehen, sind Deko oder werden falsch gelesen.
• Kein Owner, kein Datum. Ein Diagramm im Wiki ohne bekannten Autor wird mit der Zeit zur Quelle falscher Informationen.

Das Diagramm aktuell halten

Ein Diagramm nützt nur, solange man ihm vertraut. Ein paar Gewohnheiten helfen:

• Leg das Diagramm nah an die Doku des Systems und verlinke es aus README oder Runbook.
• Nimm „Diagramm aktualisiert?“ in die Checkliste von Pull Requests auf, die die Architektur ändern.
• Halte vor größeren Änderungen eine Revision fest, damit „Wie sah das letztes Quartal aus?“ eine Antwort hat.
• Plane ein wiederkehrendes Review im Kalender des verantwortlichen Teams ein, zum Beispiel einmal pro Quartal.

Ein Softwarearchitektur-Diagramm in Archboard erstellen

Archboard ist ein gehosteter Architektur-Workspace für Plattform- und Produktteams. Die Schritte oben funktionieren mit jedem Tool; in Archboard sehen sie so aus:

1. Anmelden. Melde dich über die Login-Seite mit Google oder GitHub an. Bei der ersten Anmeldung werden dein Account und deine Organisation angelegt; keine Kreditkarte nötig.
2. Packs wählen. Archboard hat 27 eingebaute Packs mit 223 Node-Typen. Für ein erstes Diagramm reichen meist diese:
   • C4 Model: Person, Software System, Container, Component, Database und Boundaries, für Context- und Container-Sichten.
   • Kubernetes: Namespace (als Frame gezeichnet), Deployment, Pod, Service, Ingress, ConfigMap, Secret, PVC, HPA, NetworkPolicy und mehr.
   • Cloud: für Cloud-Infrastruktur, inklusive eines k8s-cluster-Nodes für Multi-Account-Karten.
   • Network: für Netzwerkzonen und Verbindungen.
3. Ports verbinden. Nodes sind vollwertige Nodes mit Ports, keine generischen Formen. Zieh eine Verbindung von Port zu Port und beschrifte sie mit Protokoll und Zweck.
4. Mit Frames gruppieren. Nutze den Frame aus dem Core-Pack für Netzwerkzonen und Regionen, den Kubernetes-Namespace für Namespaces und C4-Boundaries für die Systemgrenze.
5. Titel und Legende ergänzen. Leg einen Markdown-Block oder eine Table auf den Canvas, damit Titel, Datum, Owner und Legende an einer Stelle stehen.
6. Teilen. Schick den öffentlichen Share-Link an die Person, die reviewt (im Free-Plan mit Archboard-Branding). In Pro und Enterprise kannst du das Diagramm per iframe in deine Doku-Site einbetten.
7. Exportieren. Exportiere SVG oder PNG (im Free-Plan mit Wasserzeichen); Pro bietet zusätzlich JPEG, PDF und animierte GIF / WebM, alle ohne Wasserzeichen. Das Diagramm-Dokument lässt sich außerdem als strukturiertes JSON exportieren.

Änderungen werden automatisch gespeichert, und jedes Diagramm behält Revisionen: die letzten 5 auf Free, ein Jahr Verlauf auf Pro und einen zeitlich unbegrenzten Verlauf auf Enterprise. Free enthält alle eingebauten Packs, 3 Diagramme und 15 Diagramm-Nodes plus 150 Notizen, Texte, Sticker & Mindmap-Themen pro Diagramm – mehr als genug für ein erstes Kontextdiagramm. Für vollständige Deployment-Karten schaltet Pro unbegrenzte Diagramme und Nodes frei. Details findest du unter Preise.

Bevor du loslegst, sieh dir die Beispielgalerie an: Öffne ein öffentliches Beispiel und kopiere es mit Dieses Beispiel verwenden in deinen Workspace (es zählt zu deiner Diagrammquote). Für C4- und Kubernetes-Details siehe die Seiten C4-Anwendungsfall und Kubernetes-Anwendungsfall. Auch erste Ideen können auf demselben Canvas beginnen: Archboard hat Sticky Notes und Mindmaps direkt neben den Architektur-Packs.

Checkliste und FAQ

Vor dem Veröffentlichen:

• Leser und Frage sind aufgeschrieben
• Die Grenze ist klar, externe Systeme sind einzelne Kästen
• Jeder Pfeil hat eine Richtung und ein Label mit Protokoll + Zweck
• Gruppen zeigen echte Grenzen: Netzwerkzonen, Namespaces, Regionen
• Legende, Titel, Datum und Owner sind vorhanden
• Jemand, der es nicht gezeichnet hat, konnte die Frage beantworten

Was ist der Unterschied zwischen einem Architekturdiagramm und einem Flussdiagramm? Ein Architekturdiagramm zeigt Struktur: welche Komponenten es gibt und wie sie verbunden sind. Ein Flussdiagramm (Flowchart) zeigt die Schritte und Entscheidungspunkte eines Prozesses. Wenn die zeitliche Reihenfolge einer Anfrage zählt, nimm ein Sequenzdiagramm.

Wie viele Diagramme sollte ich zeichnen? Eines pro Kombination aus Leser und Frage. Für die meisten Systeme sind ein Context-, ein Container- und ein Deployment-Diagramm ein guter Start.

Welches Tool sollte ich nutzen? Eines, das die Konzepte kennt, die du zeichnest. Archboard liefert Kubernetes-, C4- und Cloud-Konzepte als fertige Nodes mit Ports, sodass dein Diagramm lesbar bleibt und sich leicht aktuell halten lässt. Am Ende zählt, ob das Diagramm deine Frage beantwortet.

Kostenlos starten – ein Seat, keine Kreditkarte.