Ein C4-Diagramm ist eine standardisierte Methode zur architektonischen Visualisierung, die entwickelt wurde, um Software-Systeme auf mehreren Ebenen der strukturellen Abstraktion zu modellieren. In Mermaid.js integriert, folgt diec4Engine den vier Kernschichten des C4-Modells:Kontext (das Makro-Ökosystem),Container (Anwendungen, Dienste und Datenbanken),Komponenten (interne strukturelle Module), undDynamische Interaktionen. Dieses Werkzeug beseitigt die Mühe bei der Anpassung von benutzerdefiniertem CSS-Styling, indem es konsistente, präsentationsfertige architektonische Blöcke auf Basis Ihrer Textangaben anwendet.
Verständnis von C4-Diagramm-Abstraktionen & Schlüsselwörtern
Mermaid unterstützt vier spezialisierte Diagramm-Initialisierungs-Header, abhängig vom Detailgrad, den Ihre Systemstruktur erfordert:
C4Context: Fokussiert sich auf die Gesamtsicht, zeigt Benutzer, zentrale Software-Ökosysteme und externe Abhängigkeiten auf hoher Ebene.C4Container: Zoomt eine Ebene weiter hinein, um selbstständige Anwendungen, Frontend-Schnittstellen, Mikrodienste, Datenbankspeichersysteme und Warteschlangen zu analysieren.C4Component: Gräbt sich tief in einen Container hinein, um interne modulare Komponenten auf Code-Ebene zu zeigen, wie z. B. Controller, Dienste und Repositories.C4Dynamic: Fokussiert sich auf die Verfolgung von Laufzeit-Dateninteraktionen oder schrittweisen Ablauffolgen von Transaktionen zwischen Infrastrukturblöcken.
Grundlegende Syntaxstruktur
Jedes C4-Diagramm beginnt mit seinem spezifischen Ebenen-Header, gefolgt von einer optionalen Titelangabe und durch Kommas getrennten Makrokomponenten. Die Parameter befinden sich in Klammern, wobei Zeichenketten durch doppelte Anführungszeichen begrenzt sind.
C4Context
title "Systemkontext-Entwurf für das Internet-Kernnetz"
Person(kunde, "Bankkunde", "Ein Kunde der Bank mit persönlichen Konten.")
System(banking_system, "Internet-Banking-System", "Ermöglicht Kunden das Ansehen von Kontoinformationen.")
Rel(kunde, banking_system, "Nutzt", "HTTPS")
Die vollständige Makro-Taxonomie der C4-Elemente
Die Mermaid-C4-Bibliothek bietet eine umfangreiche Auswahl an spezialisierten Makros, um klar zwischen internen Komponenten, externen Systemen und Datenbank-Ebenen auf allen Abstraktionsebenen zu unterscheiden.
1. Personen- und Benutzer-Makros
Person(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Modelliert einen internen menschlichen Benutzer oder Interessenten.Person_Ext(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Modelliert einen externen Benutzer (z. B. einen Drittanbieter oder Prüfer) außerhalb Ihrer zentralen organisatorischen Grenze.
2. System- und Software-Ökosystem-Makros
System(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Stellt einen internen, im Umfang liegenden Software-System-Cluster unter Ihrer direkten Verwaltung dar.System_Ext(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Modelliert ein entscheidendes externes Software-System, das von einem Dritten verwaltet wird (z. B. Identitätsanbieter, Kernbankbuchhaltungen).SystemDb(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Zeichnet eine systemnahe Datenbankbox in Form eines Zylinders.SystemDb_Ext(alias, Bezeichnung, [Beschreibung], [Sprite], [Tags]): Zeichnet eine externe, von einem Dritten bereitgestellte Datenbank-Ebene.
3. Container-Ebene-Makros (C4Container-Ebene)
Container(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Modelliert eine eigenständige ausführbare Anwendung, API-Server oder Frontend-Schnittstelle.ContainerDb(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Zeichnet einen Wrapper für eine relationale oder nicht-relationale Datenbank-Engine auf Container-Ebene.Container_Ext(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Stellt einen externen Cloud-Container oder Anwendungsdienst dar.ContainerDb_Ext(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Stellt eine externe, verwaltete Cloud-Datenbank-Speicher-Ebene dar.
4. Komponenten-Ebene-Makros (C4Component-Ebene)
Komponente(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Abbildung eines internen Moduls auf Code-Ebene, einer Schicht oder eines Klassen-Controllers.KomponenteDb(alias, Bezeichnung, Technologie, [Beschreibung], [Sprite], [Tags]): Modelliert ein internes Mikro-Komponenten-Speichersystem oder ein System zur Low-Level-Dateicaching.
Grenzcontainer und strukturelle Umhüllung
Um Sicherheitsbereiche, Unternehmens-Firewalls oder logische Anwendungsgrenzen anzugeben, bietet Mermaid drei spezielle, eckige Klammern umschlossene Container-Wrapper. Elemente innerhalb werden visuell zusammengefasst.
Unternehmensgrenze(alias, label) { ... }: Umfasst hochrangige Systeme innerhalb einer breiten visuellen Grenze, die den gesamten Unternehmens- oder Firmeninfrastrukturumfang darstellt.Systemgrenze(alias, label) { ... }: Gruppiert eng verwandte Anwendungskomponenten oder Mikrodienste innerhalb einer einheitlichen Softwareökosystembox.Containergrenze(alias, label) { ... }: Isoliert komponenten auf Code-Ebene innerhalb einer einzelnen Anwendungsmodule-Kontextschicht.
Erweiterte Beziehungspfeil-Operatoren
Die Verbindung von Blöcken in C4-Diagrammen beruht auf der RelMakro oder ihren explizit gerichteten Varianten. Anstatt Rohflussdiagrammlinien zu übergeben, verfolgen Sie Verbindungen semantisch, indem Sie Technologievektoren direkt innerhalb der Logikblöcke deklarieren.
| Beziehungssyntax-Token | Visuelle Pfeilrichtung | Verwendungs-Ausrichtungs-Kontext |
|---|---|---|
Rel(von, zu, Beschriftung, [technologie]) |
Dynamisch / Automatisiert | Standardbeziehung. Lassen Sie den Layout-Algorithmus den besten Linienweg bestimmen. |
BiRel(von, zu, Beschriftung, [technologie]) |
Zweiseitig (<–>) | Zeigt zweidirektionale interaktive Handshakes, Duplex-Protokolle oder Synchronisationsprozesse an. |
Rel_Zurück(von, zu, Beschriftung, [technologie]) |
Rückwärts gerichteter Pfeil oben (<–) | Zeichnet die Beziehung in der Code-Logik vorwärts, dreht aber den sichtbaren visuellen Pfeil rückwärts. |
Rel_Nachbar(von, zu, Beschriftung, [technologie]) |
Horizontale Anordnung bevorzugen | Zwingt den Zielknoten, direkt neben dem Quellknoten in derselben horizontalen Reihe zu bleiben. |
Rel_NachUnten(von, zu, Beschriftung, [technologie]) / Rel_N(...) |
Gerade nach unten (v) | Zwingt vertikale Datenflüsse nach unten zu Datenbank-Ebenen oder nachfolgenden Hintergrundprozessen. |
Rel_Up(von, zu, beschriftung, [technologie]) / Rel_U(...) |
Gerade nach oben (^) | Zwingt Beziehungstracks, geradewegs zu den Client-UI-Komponenten zu verlaufen. |
Rel_Left(von, zu, beschriftung, [technologie]) / Rel_L(...) |
Gerade nach links (<-) | Leitet Pfade horizontal auf die linke Seite des Canvas-Elements aus. |
Rel_Right(von, zu, beschriftung, [technologie]) / Rel_R(...) |
Gerade nach rechts (->) | Leitet Pfade horizontal auf die rechte Seite des Canvas-Elements aus. |
Benutzerdefinierte dynamische Stilisierung und Kennzeichnung (C4-Form-Überschreibungen)
Um veraltete Anwendungen zu kennzeichnen, Premium-Systeme hervorzuheben oder sichere Datenflüsse zu markieren, können Sie benutzerdefinierte Stile mithilfe der Element-Tag-Engine erstellen. Sie definieren eine Matrix mit Tag-Eigenschaften am Anfang Ihres Dokuments und fügen dann diese Tag-Beschriftung an Ihre Elementdefinitionen an.
Stiländerungs-Schlüsselwörter:
UpdateElementStyle(elementName, hintergrundFarbe, schriftFarbe, [randFarbe], [schatten]): Direkte Überschreibung der Standard-Hintergrundpalette einer expliziten Elementbox.UpdateRelStyle(von, zu, linienFarbe, textFarbe): Zielgerichtet eine Verbindungsroute, um Linienpfade oder Verbindungsbeschreibungen umzufärben.
C4Context
titel "Benutzerdefinierte farbcodierte globale Architekturkarte"
System(legacy_api, "Legacy-Rechnungsstellungskern", "Verarbeitet die Verlängerung von Abonnements.")
System(modern_portal, "Kunden-Dashboard-Portal", "Modernes Benutzer-Web-View-Engine.")
%% Direkte Farb-Anpassungen
UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Realitätsnaher Bauplan: Enterprise-E-Commerce-System-Grenzcontainer-Karte
Dieser umfassende, mehrschichtige Container-Bauplan verfolgt ein Online-E-Commerce-Ökosystem. Er isoliert interne Kern-Server mithilfe eines System_Grenze Block-Container, implementiert externe Cloud-Benachrichtigungs-Relais über System_Ext, ordnet interne relationale Datenbank-Speicher neben externen Tracking-Mikrodiensten zu und fixiert Kommunikations-Pipelines mithilfe expliziter Technologie-Stack-Parameter.
C4Container
title "Container-Blueprint für Enterprise-E-Commerce-Plattform"
Person(kunde, "Online-Käufer", "Durchsucht Katalogartikel und fügt Produkte in ihren digitalen Warenkorb ein.")
System_Ext(zahlungs_gateway, "Stripe-API-Dienst", "Drittanbieter-Kreditkarten-Tresor und Verarbeitungsmotor.")
System_Boundary(e_commerce_grenze, "Kernbereich E-Commerce") {
Container(frontend_app, "Web-App für Verkaufsstelle", "Next.js, React", "Stellt statische Assets bereit und verwaltet Benutzer-Warenkorb-Sitzungen.")
Container(checkout_service, "Checkout-Mikrodienst", "Node.js, Express", "Verarbeitet Warenkorb-Workflows und berechnet Steuern.")
ContainerDb(bestell_ledger_db, "Bestell-Ledger-Datenbank", "PostgreSQL", "Speichert historische Transaktionszeilen und sichere Ledger-Einträge.")
}
%% Architektonische Interaktionspfade
Rel(kunde, frontend_app, "Betrachtet Produkte und stellt Bestellungen über", "HTTPS/Browser")
Rel_Down(frontend_app, checkout_service, "Sendet Einkaufs-Payload-Transaktionen über", "JSON/REST-API")
Rel_Right(checkout_service, bestell_ledger_db, "Speichert transaktionale Zustände innerhalb", "SQL/JDBC-Verbindung")
Rel_Left(checkout_service, zahlungs_gateway, "Autorisiert tokenisierte Belastungsanrufe mit", "Sichere TLS/HTTPS-API")
Häufige Syntax-Fallen & Systembeschränkungen
Beim Kompilieren sauberer C4-Abbildungen für Software-Frameworks, achten Sie auf diese Ausführungsparameter, um das Brechen der Diagramme zu verhindern:
- Komma-Trennzeichen-Formatierung: Im Gegensatz zu fast jedem anderen Mermaid-Schema erfordern C4-Makros strenge Kommata zwischen Parametern:
Person(id, "Beschriftung", "Beschreibung"). Das Vergessen eines trennenden Kommas führt vollständig zum Absturz des Layout-Generators. - Reservierte Bezeichnungs-Anführungszeichen: Anzeigefelder, Technologie-Tags und Beschreibungsblöcke innerhalb von Makros *müssen* in klaren doppelten Anführungszeichen eingeschlossen werden. Das Einfügen von Roh-Texten in Felder ohne Anführungszeichen führt zu fehlerhaften Parsing-Fehlern, die das Diagramm beschädigen.
- Reihenfolge der Grenzverschachtelung: Wenn Elemente innerhalb einer
System_BoundaryoderEnterprise_BoundaryBlock müssen Sie deren Arbeitsrauminhalt explizit mit Standard-Klammern{ }leer machen. Ein offener Grenz-Bracket oder falsche Übereinstimmung bricht die Darstellungslayouts. - Dynamische Alias-Instanziierung: Sie können keine Beziehungen (
Rel) zu einem Alias-Bezeichner zeichnen, der nicht explizit durch ein Element-Makro-Block darüber initialisiert wurde. Halten Sie Ihren Deklarationsablauf kontinuierlich von oben nach unten laufend.