Das System-Context-Diagramm ist Ebene 1 des C4-Modells -- das mit Abstand wichtigste Architekturdiagramm, das Ihr Team erstellen kann. Dieser Leitfaden erklärt, was in ein C4-Context-Diagramm gehört, führt durch ein vollständiges Beispiel und zeigt, wie Sie eines manuell erstellen oder aus Ihrem Code generieren.

C4 System Context Diagram: Vollständiger Leitfaden mit Beispielen

Wenn Sie nur ein einziges Architekturdiagramm zeichnen, dann machen Sie es zu einem System-Context-Diagramm. Es ist der Einstiegspunkt in das C4-Modell, das Diagramm, das jeder Stakeholder ohne Schulung lesen kann, und der schnellste Weg, um Meinungsverschiedenheiten darüber offenzulegen, was Ihr System eigentlich tut.

Doch die meisten Teams machen es falsch. Sie stopfen Datenbanken, Microservices und Kubernetes-Cluster hinein, bis das „Context"-Diagramm zu einer unlesbaren Infrastrukturkarte wird. Oder sie überspringen es vollständig und springen direkt zu einem Container-Diagramm, sodass nicht-technische Stakeholder mit nichts dastehen, das sie verstehen können.

Dieser Leitfaden ist eine ausführliche Betrachtung von C4-Modell-Ebene 1: was ein System-Context-Diagramm ist, was genau hineingehört (und was nicht), ein vollständig durchgearbeitetes Beispiel, die Fehler, die die meisten Context-Diagramme ruinieren, und ein schrittweiser Prozess zum Erstellen eines solchen Diagramms -- von Hand oder generiert aus Ihrer Codebasis. Wenn Sie mit dem C4-Modell selbst noch nicht vertraut sind, beginnen Sie mit unserem vollständigen Leitfaden zum C4-Modell und kommen Sie dann zurück.

Was ist ein System-Context-Diagramm?

Ein System-Context-Diagramm ist das erste und höchste Diagramm im C4-Modell. Es zeigt ein Softwaresystem als einzelne Box und beantwortet eine einzige Frage: Wie fügt sich dieses System in seine Umgebung ein?

Wie die Glossardefinition es formuliert, konzentriert sich das System-Context-Diagramm auf die Personen und externen Systeme, die mit dem beschriebenen System interagieren, und lässt die interne Struktur bewusst weg. Sein Ziel ist es, den Umfang festzulegen: wer das System nutzt, von welchen Systemen es abhängt und welche Systeme von ihm abhängen.

Drei Arten von Elementen erscheinen auf einem Context-Diagramm, und nur drei:

Ihr Softwaresystem -- eine Box, in der Mitte. Nicht seine Services, nicht seine Datenbanken. Eine Box.
Personen -- die Nutzer, Rollen oder Personas, die mit dem System interagieren. Ein „Kunde", ein „Administrator", ein „Support-Mitarbeiter".
Externe Softwaresysteme -- die Systeme, mit denen Ihres kommuniziert, die Ihr Team aber nicht selbst betreibt: ein Payment-Gateway, ein E-Mail-Anbieter, ein Legacy-ERP, ein Identity Provider.

Verbunden werden sie durch Beziehungen: beschriftete Pfeile, die beschreiben, wer was tut. „Gibt Bestellungen auf über", „Sendet Zahlungsanfragen an", „Empfängt Versand-Updates von".

Das ist das gesamte Vokabular. Boxen für das System, die Personen und die externen Systeme; Pfeile für Beziehungen. Die Disziplin des Diagramms entsteht durch das, was Sie weglassen.

Wer ist die Zielgruppe?

Das System-Context-Diagramm ist unter den vier C4-Ebenen einzigartig, weil es für alle gedacht ist -- auch für Menschen, die nie eine Zeile Code lesen werden:

Nicht-technische Stakeholder. Ein Product Manager, ein CEO oder ein Compliance-Verantwortlicher kann sich ein Context-Diagramm ansehen und in unter einer Minute den Zweck des Systems, seine Nutzer und seine Drittanbieter-Abhängigkeiten verstehen.
Neue Teammitglieder. Bevor ein neuer Entwickler Ihre Ordnerstruktur lernt, sollte er die Grenze Ihres Systems lernen. Das Context-Diagramm ist Onboarding-Folie Nummer eins.
Architekten und Security-Reviewer. Jeder Pfeil, der die Systemgrenze überschreitet, ist ein Integrationspunkt, ein Datenfluss und eine potenzielle Angriffsfläche. Security- und Compliance-Reviews beginnen oft genau hier.
Andere Teams. Wenn ein anderes Team fragt „ruft euer System die Billing-API direkt auf?", beantwortet das Context-Diagramm die Frage ohne ein Meeting.

Deshalb gehören Technologieentscheidungen hier nicht hin. In dem Moment, in dem Sie „PostgreSQL" oder „Kafka" auf ein Context-Diagramm schreiben, haben Sie die Zielgruppe auf Ingenieure eingeengt -- und dafür haben Sie das Container-Diagramm.

Was in ein Context-Diagramm gehört (und was nicht)

Einbeziehen

Das betrachtete System -- genau eine Box, klar benannt.
Jede Kategorie von Nutzern -- keine einzelnen Personen, sondern Rollen oder Personas. Wenn Kunden und Lagerpersonal das System unterschiedlich nutzen, sind das zwei separate Personen-Boxen.
Jede externe Systemabhängigkeit -- einschließlich derer, die Sie für selbstverständlich halten: der E-Mail-Dienst, der Identity Provider, die Analytics-Plattform, der Monitoring-Stack, sofern architektonisch relevant.
Systeme, die von Ihnen abhängen -- wenn das System eines Partners Ihre API konsumiert, gehört es mit dem Pfeil in Ihre Richtung auf das Diagramm.
Beschriftete Beziehungen -- jeder Pfeil braucht eine Verbphrase. Ein unbeschrifteter Pfeil ist ein Fragezeichen.

Ausschließen

Container -- keine Web-Apps, keine API-Services, keine Datenbanken, keine Message Queues. Das ist Ebene 2.
Technologieentscheidungen -- kein „React", kein „Go", kein „PostgreSQL". Ein Context-Diagramm sollte eine vollständige Neuentwicklung Ihres Stacks überstehen, ohne sich zu ändern.
Interne Struktur externer Systeme -- Stripe ist eine Box, kein Diagramm der Architektur von Stripe.
Infrastruktur- und Deployment-Details -- keine Regionen, keine Cluster, keine Load Balancer.
Einzelne Features -- das Diagramm zeigt Beziehungen, keine Feature-Liste.

Ein einfacher Test: Wenn das Entfernen eines Elements nicht ändern würde, wer mit dem System interagiert oder welche externen Systeme es berührt, dann gehört dieses Element nicht auf Ebene 1.

Ein vollständiges Context-Diagramm-Beispiel: Online-Zahlungsplattform

Arbeiten wir ein realistisches Beispiel durch. Stellen Sie sich vor, Sie dokumentieren PayFlow, eine Online-Zahlungsplattform, mit der Händler auf ihren Websites Kartenzahlungen akzeptieren können.

Schritt 1: Das System benennen

Eine Box in der Mitte: PayFlow Payment Platform. Geben Sie ihr eine einzeilige Beschreibung: „Ermöglicht Händlern, Online-Kartenzahlungen zu akzeptieren und zu verwalten."

Schritt 2: Die Personen identifizieren

Wer interagiert mit PayFlow, und in welcher Rolle?

Händler -- ein Geschäftsinhaber, der Zahlungsseiten konfiguriert, Transaktionen einsieht und Rückerstattungen auslöst.
Endkunde -- ein Käufer, der einen Einkauf über ein PayFlow-Checkout bezahlt.
Support-Mitarbeiter -- internes Personal, das strittige Transaktionen untersucht.

Schritt 3: Die externen Systeme identifizieren

Wovon hängt PayFlow ab, und was hängt von PayFlow ab?

Kartennetzwerke / Acquiring Bank -- autorisiert und verrechnet Kartentransaktionen.
Fraud-Detection-Service -- bewertet Transaktionen auf Betrugsrisiko.
E-Mail-Dienst -- versendet Belege und Benachrichtigungen.
Identity Provider -- übernimmt das Single Sign-on der Händler.
E-Commerce-Site des Händlers -- die eigene Website des Händlers, die das PayFlow-Checkout einbettet und die PayFlow-API konsumiert.
Buchhaltungsplattform -- empfängt Abrechnungsberichte für die Buchführung des Händlers.

Schritt 4: Die Beziehungen zeichnen

Die vollständige Liste der Elemente und Beziehungen sieht so aus:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

Insgesamt zehn Elemente: ein System, drei Personen, sechs externe Systeme. Jeder Pfeil hat eine Verbphrase. Es gibt keine Erwähnung von Services, Datenbanken, Queues oder Programmiersprachen -- und doch versteht jeder, der dieses Diagramm liest, was PayFlow ist, wer es nutzt und wovon es abhängt.

Beachten Sie, was dieses Diagramm sofort sichtbar macht:

Compliance-Oberfläche. Kartennetzwerke und Fraud Detection auf dem Diagramm verraten einem Security-Reviewer genau, wo PCI-relevante Daten fließen.
Anbieterrisiko. Sechs externe Abhängigkeiten, jede ein potenzieller Ausfallpunkt oder ein Verhandlungsthema im Vertrag.
Beidseitige Grenze. Die E-Commerce-Site des Händlers ruft in PayFlow hinein -- das System ist nicht nur ein Konsument anderer Dienste, es ist selbst eine Abhängigkeit für jemand anderen.

Das ist die Art von Gespräch, die ein Context-Diagramm anstoßen soll.

Häufige Fehler in System-Context-Diagrammen

Fehler 1: Zu viele Details

Der häufigste Fehlschlag. Das Diagramm beginnt sauber, dann fügt jemand „nur die Hauptdatenbank" hinzu, dann das API-Gateway, dann die drei zentralen Microservices, und innerhalb eines Monats ist es ein Container-Diagramm im Gewand eines Context-Diagramms. Die Lösung ist gnadenlos: Ihr System ist eine Box. Wenn Sie den Drang verspüren, Interna zu zeigen, ist das das Signal, ein Container-Diagramm als separate, verlinkte Ansicht zu erstellen -- nicht dieses hier zu überladen.

Fehler 2: Fehlende externe Abhängigkeiten

Teams vergessen zuverlässig die Abhängigkeiten, die sie für langweilig halten: den E-Mail-Anbieter, das SMS-Gateway, den Identity Provider, das CDN, den Feature-Flag-Service. Aber „langweilige" Abhängigkeiten verursachen echte Ausfälle und echtes Vendor-Lock-in. Gehen Sie Ihre Konfigurationsdateien und Umgebungsvariablen durch -- jeder API-Schlüssel entspricht in der Regel einem externen System, das auf das Diagramm gehört.

Fehler 3: Vermischung von Abstraktionsebenen

Ein Diagramm, das „Customer → Web App → Orders API → PostgreSQL → Stripe" zeigt, vermischt eine Person, zwei Container, eine Datenbank und ein externes System in einer einzigen flachen Ansicht. Leser können nicht erkennen, wo Ihre Systemgrenze liegt. Jedes C4-Diagramm sollte auf genau einer Zoom-Ebene leben; der ganze Sinn der Hierarchie des C4-Modells ist, dass Sie zwischen Diagrammen hineinzoomen, niemals innerhalb eines einzigen.

Fehler 4: Unbeschriftete oder vage Beziehungen

„Verwendet" ist keine Beziehungsbeschriftung -- alles „verwendet" alles. Schreiben Sie, was tatsächlich passiert: „Übermittelt Bestellungen über", „Empfängt Webhook-Events von", „Authentifiziert sich gegen". In den Beschriftungen steckt der größte Teil der Information des Diagramms.

Fehler 5: Es einmal zeichnen und nie aktualisieren

Ein Context-Diagramm aus 2023, das immer noch das Legacy-CRM zeigt, von dem Sie letztes Jahr migriert sind, ist aktiv irreführend. Context-Diagramme ändern sich seltener als Diagramme tieferer Ebenen, aber sie ändern sich -- bei jeder neuen Anbieterintegration, bei jeder veralteten Partner-API. Behandeln Sie das Diagramm als lebende Dokumentation, nicht als Kickoff-Artefakt.

Wie man ein System-Context-Diagramm erstellt: Schritt für Schritt

Der manuelle Ansatz

System benennen und beschreiben. Ein Satz: Was tut es, für wen?
Die Nutzerrollen auflisten. Sammeln Sie jede eigenständige Persona, die mit dem System interagiert. Führen Sie Rollen zusammen, die identisch interagieren; trennen Sie Rollen, die das nicht tun.
Die externen Systeme auflisten. Gehen Sie Integrationen, API-Schlüssel, Webhooks und geplante Exporte durch. Beziehen Sie Systeme ein, die Sie aufrufen, nicht nur Systeme, die Sie selbst aufrufen.
Die Beziehungen zeichnen. Ein Pfeil pro bedeutsamer Interaktion, jeweils mit einer Verbphrase beschriftet. Die Richtung folgt der Initiative: Wer löst die Interaktion aus?
Mit dem Team durchsehen. Das ist der wertvollste Schritt. Ein 30-minütiger Review bringt zuverlässig Meinungsverschiedenheiten ans Licht: „Moment, rufen wir diesen Service überhaupt noch auf?", „Seit wann greifen Partner direkt auf unsere API zu?" Diese Diskussionen sind das Ergebnis.
Veröffentlichen Sie es dort, wo Menschen es finden -- nicht vergraben auf einer Wiki-Seite, die niemand besucht.

Für das Zeichnen selbst funktioniert jedes Werkzeug: ein Whiteboard, diagrams.net, Structurizr, PlantUML mit C4-Erweiterungen. Der Engpass war nie das Zeichnen -- es sind die Schritte 2, 3 und 5 und das Aktuellhalten des Ergebnisses über die Zeit.

Der automatisierte Ansatz: Context-Diagramme mit Archyl generieren

Hier geht Archyl einen anderen Weg als Zeichenwerkzeuge. Statt von einer leeren Leinwand zu starten, verbinden Sie Ihre Repositories und führen die AI Discovery aus: Archyl analysiert Ihre Codestruktur, Konfigurationsdateien und Abhängigkeitsgraphen und schlägt dann ein Entwurfs-C4-Modell vor -- Systeme, externe Abhängigkeiten, Container, Komponenten und die Beziehungen zwischen ihnen. Sie prüfen jeden Vorschlag, nehmen ihn an oder passen ihn an, und die System-Context-Ansicht wird automatisch aus dem Modell gerendert.

Weil das Diagramm aus einem Modell generiert und nicht von Hand gezeichnet wird, folgen daraus zwei Dinge:

Die Ebenen bleiben verbunden. Die System-Box in Ihrem Context-Diagramm ist genau dieselbe Entität, in die Sie für die Container-Ansicht hineinzoomen. Kein Copy-Paste-Drift zwischen Diagrammen.
Veralten wird messbar. Die Drift-Erkennung von Archyl vergleicht kontinuierlich Ihre dokumentierte Architektur mit dem, was tatsächlich in der Codebasis existiert. Wenn also eine Integration entfernt oder ein Service umbenannt wird, erfahren Sie es aus einem Drift-Score statt von einem verwirrten neuen Kollegen.

Wenn Sie Dokumentation bevorzugen, die in der Versionskontrolle lebt, unterstützt Archyl auch einen Architecture-as-Code-Workflow: Definieren Sie Ihr C4-Modell in YAML, committen Sie es neben Ihren Code und lassen Sie die Diagramme aus dieser Definition rendern.

Vom Context zu den Containern

Das System-Context-Diagramm legt die Grenze fest; die nächste Ebene öffnet die Box. Sobald Ihr Context-Diagramm stabil ist, ist der natürliche nächste Schritt das Container-Diagramm -- die Ansicht auf Ebene 2, die die deploybaren Einheiten (Web-Apps, APIs, Datenbanken, Broker) innerhalb Ihres Systems und ihre Kommunikation zeigt. Das behandeln wir ausführlich in unserem Leitfaden zum C4-Container-Diagramm.

Die Reihenfolge ist wichtig. Teams, die das Context-Diagramm überspringen und auf Ebene 2 beginnen, neigen dazu, Container-Diagramme mit unscharfen Grenzen zu produzieren -- externe Systeme vermischt mit internen Services, weil sich nie jemand darauf geeinigt hat, wo das System endet.

FAQ

Was ist der Unterschied zwischen einem System-Context-Diagramm und einem Container-Diagramm?

Das Context-Diagramm (Ebene 1) zeigt Ihr System als einzelne Box und konzentriert sich auf seine Umgebung: Nutzer und externe Systeme. Das Container-Diagramm (Ebene 2) zoomt in diese Box hinein, um deploybare Einheiten zu zeigen -- Web-Apps, Services, Datenbanken -- und ihre Technologieentscheidungen. Context beantwortet „Womit interagiert dieses System?"; Container beantworten „Woraus besteht dieses System?".

Wie viele Elemente sollte ein Context-Diagramm haben?

Es gibt keine feste Regel, aber die meisten gesunden Context-Diagramme haben ein System, zwei bis fünf Nutzerrollen und drei bis zehn externe Systeme. Wenn Sie über fünfzehn oder zwanzig Elemente hinaus sind, ist entweder Ihre Systemgrenze zu weit gefasst, oder Sie dokumentieren eine Unternehmenslandschaft -- in diesem Fall passt das C4-System-Landscape-Diagramm (mehrere Systeme in einer Ansicht) besser.

Sollten Datenbanken auf einem System-Context-Diagramm erscheinen?

Nein -- solange die Datenbank zu Ihrem System gehört, ist sie ein internes Detail und erscheint auf der Container-Ebene. Die Ausnahme ist eine Datenbank, die von einem anderen Team oder Anbieter betrieben wird und aus der Ihr System direkt liest; das ist faktisch ein externes System und kann als solches erscheinen.

Ist ein C4-Context-Diagramm dasselbe wie ein UML- oder Datenfluss-Context-Diagramm?

Konzeptionell sind sie verwandt -- die Idee eines „Context-Diagramms" (ein System, seine Umgebung) ist älter als C4 und existiert in der strukturierten Analyse und der UML-Praxis. Die C4-Variante zeichnet sich durch ihren Platz in einer Hierarchie aus: Jedes Element darauf lässt sich in die nächste Ebene zerlegen, was Ihnen eine navigierbare Karte statt eines eigenständigen Bildes liefert.

Bereit, Ihr System-Context-Diagramm zu erstellen? Probieren Sie Archyl kostenlos aus und generieren Sie ein C4-Modell direkt aus Ihren Repositories. Oder lesen Sie weiter: Was ist das C4-Modell? Ein vollständiger Leitfaden | Leitfaden zum C4-Container-Diagramm | System-Context-Diagramm im Glossar.

C4 System Context Diagram: Vollständiger Leitfaden mit Beispielen - Archyl Blog