Mermaid.js C4ダイアグラム構文とアーキテクチャガイド

C4ダイアグラムは、構造的抽象の複数のレベルでソフトウェアシステムをモデル化することを目的とした標準化されたアーキテクチャ可視化手法です。Mermaid.jsにネイティブに組み込まれており、c4エンジンはC4モデルの4つのコア層に従います：コンテキスト（マクロエコシステム）,コンテナ（アプリケーション、サービス、データベース）,コンポーネント（内部構造モジュール）および動的相互作用。このツールは、テキスト宣言に基づいて一貫性があり、プレゼンテーション用に準備されたアーキテクチャブロックを適用することで、カスタムCSSスタイルの手間を解消します。

C4ダイアグラムの抽象化とキーワードの理解

Mermaidは、システムレイアウトに必要な詳細レベルに応じて、4つの専用の図初期化ヘッダーをサポートしています：

  • C4Context：全体像に焦点を当て、ユーザー、コアソフトウェアエコシステム、および高レベルの外部依存関係を表示します。
  • C4Container：1レベルズームインして、スタンドアロンアプリケーション、フロントエンドインターフェース、マイクロサービス、データベースストレージシステム、キューを分解します。
  • C4Component：コンテナ内部に深く掘り下げ、コントローラー、サービス、リポジトリなどのコードレベルのモジュールを紹介します。
  • C4Dynamic：ランタイム中のデータ相互作用や、インフラストラクチャブロック間のステップバイステップのトランザクションシーケンスを追跡することに焦点を当てます。

基本構文構造

すべてのC4ダイアグラムは、特定の層ヘッダーから始まり、オプションのタイトル文とコンマ区切りのマクロコンポーネントが続きます。パラメータは括弧内に格納され、文字列は二重引用符で囲まれます。

Mermaid VPasCodeでMermaidを編集
Mermaid Edit Mermaid in VPasCode 
C4Context
  タイトル "インターネットコアのシステムコンテキスト設計図"
  パーソン(customer, "銀行顧客", "個人口座を持つ銀行の顧客です。")
  システム(banking_system, "インターネットバンキングシステム", "顧客が口座情報を閲覧できるようにします。")
  関係(customer, banking_system, "使用", "HTTPS")
Edit Mermaid in VPasCode
VPasCodeでMermaidを編集

完全なC4要素マクロ分類

Mermaid C4ライブラリは、すべての抽象層において内部コンポーネント、外部システム、データベースレイヤーを明確に区別できる広範な専用マクロを提供しています。

1. ユーザーおよびユーザーマクロ

  • Person(別名, ラベル, [説明], [スプライト], [タグ]): 組織内の人物ユーザーまたは関係者をモデル化します。
  • Person_Ext(別名, ラベル, [説明], [スプライト], [タグ]): 核心組織境界外の外部ユーザー（例：第三者ベンダーまたは監査担当者）をモデル化します。

2. システムおよびソフトウェアエコシステムマクロ

  • System(別名, ラベル, [説明], [スプライト], [タグ]): 直接管理下にある、内部の対象範囲内のソフトウェアシステムクラスタを表します。
  • System_Ext(別名, ラベル, [説明], [スプライト], [タグ]): 第三者によって管理される重要な外部ソフトウェアシステム（例：IDプロバイダー、基幹銀行帳簿）をモデル化します。
  • SystemDb(別名, ラベル, [説明], [スプライト], [タグ]): システムレベルのデータリポジトリボックスを円筒形としてレンダリングします。
  • SystemDb_Ext(別名, ラベル, [説明], [スプライト], [タグ]): 外部の第三者データベース層をレンダリングします。

3. コンテナ層マクロ（C4Container層）

  • Container(別名, ラベル, 技術, [説明], [スプライト], [タグ]): 独立して実行可能なアプリケーション、APIサーバー、またはフロントエンドインターフェースをモデル化します。
  • ContainerDb(別名, ラベル, 技術, [説明], [スプライト], [タグ]): コンテナレベルのリレーショナルまたは非リレーショナルデータベースエンジンのラッパーをレンダリングします。
  • Container_Ext(別名, ラベル, 技術, [説明], [スプライト], [タグ]): 外部のクラウドコンテナまたはアプリケーションサービスを表します。
  • ContainerDb_Ext(別名, ラベル, 技術, [説明], [スプライト], [タグ]): 外部で管理されるクラウドデータベースストレージ層を表します。

4. コンポーネント層マクロ（C4Component層）

  • Component(別名, ラベル, 技術, [説明], [スプライト], [タグ]): 内部のコードレベルのモジュール、レイヤー、またはクラスコントローラーをマッピングします。
  • ComponentDb(別名, ラベル, 技術, [説明], [スプライト], [タグ]): 内部のマイクロコンポーネントストレージまたは低レベルのファイルキャッシュシステムをモデル化します。

境界コンテナおよび構造的ラッピング

セキュリティ境界、企業用ファイアウォール、または論理的なアプリケーション境界を示すために、Mermaidは3つの専用の括弧で囲まれたコンテナラッパーを提供しています。内部にネストされた要素は視覚的にグループ化されます。

  • Enterprise_Boundary(別名, ラベル) { ... }: 高レベルのシステムを、企業全体または会社のインフラストラクチャの境界を表す広い視覚的境界で囲みます。
  • System_Boundary(別名, ラベル) { ... }: 密接に関連するアプリケーションコンテナまたはマイクロサービスを、統合されたソフトウェアエコシステムボックス内にグループ化します。
  • Container_Boundary(別名, ラベル) { ... }: 単一のアプリケーションモジュールコンテキストレイヤー内に、コードレベルのコンポーネントを分離します。

高度な関係方向演算子

C4図におけるブロックの接続は、Relマクロまたは明示的に方向指定された変種に依存しています。生のフローチャートラインを渡すのではなく、論理ブロック内に直接技術ベクトルを宣言することで、接続を意味的に追跡します。

関係構文トークン 視覚的矢印の方向 使用状況の整合性コンテキスト
Rel(送信元, 受信先, ラベル, [技術]) 動的／自動 デフォルトの関係。レイアウトアルゴリズムに最適な線路パスを決定させます。
BiRel(送信元, 受信先, ラベル, [技術]) 双方向 (<–>) 双方向のインタラクティブなハンドシェイク、デュプレックスプロトコル、または同期プロセスを示します。
Rel_Back(送信元, 受信先, ラベル, [技術]) 逆向き矢印上部 (<–) コード論理上は関係を前向きに描画しますが、視覚的な矢印は逆向きに表示します。
Rel_Neighbor(送信元, 受信先, ラベル, [技術]) 水平レイアウト優先 ターゲットノードを、同じ水平行上に送信元ノードのすぐ隣に固定します。
Rel_Down(送信元, 受信先, ラベル, [技術]) / Rel_D(...) 真下方向 (v) 垂直方向のデータフローを、データベース層またはその後のバックグラウンドプロセスに強制します。
Rel_Up(開始, 終了, ラベル, [技術]) / Rel_U(...) 直上 (^) 関係トラックがクライアントUIコンポーネントへ直上に移動するように強制します。
Rel_Left(開始, 終了, ラベル, [技術]) / Rel_L(...) 直左 (<-) パスをキャンバス要素の左側に水平にルーティングします。
Rel_Right(開始, 終了, ラベル, [技術]) / Rel_R(...) 直右 (->) パスをキャンバス要素の右側に水平にルーティングします。

カスタム動的スタイル設定 & タグ付け (C4 Shapeオーバーライド)

レガシーなアプリケーションをマークしたり、プレミアムシステムを強調したり、セキュアなデータフローを強調するため、要素タグエンジンを使用してカスタムスタイルを作成できます。ドキュメントの先頭にタグプロパティ行列を定義し、その後そのタグラベルを要素定義に追加します。

スタイル変更キーワード：

  • UpdateElementStyle(要素名, 背景色, 文字色, [枠色], [影の有無]): 明示的な要素ボックスのデフォルト背景パレットへの直接オーバーライド。
  • UpdateRelStyle(開始, 終了, 線色, 文字色): 接続ルートを明示的にターゲットにして、線のパスや接続の説明を再色分けします。
Mermaid VPasCodeでMermaidを編集
Mermaid Edit Mermaid in VPasCode 
C4Context
  タイトル "カスタムカラーコード付きグローバルアーキテクチャマップ"
  
  システム(legacy_api, "レガシー請求コア", "サブスクリプションの更新処理")
  システム(modern_portal, "カスタマーダッシュボードポータル", "モダンなユーザーWebビューインジン")
  
  %% 直接的な色のカスタマイズ
  UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
  UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Edit Mermaid in VPasCode
VPasCodeでMermaidを編集

現実世界のブループリント：エンタープライズEコマースシステム境界コンテナマップ

この包括的でマルチティアードのコンテナブループリントは、オンラインEコマースエコシステムを追跡します。内部コアサーバーを「システム境界」ブロックコンテナを使用して分離し、外部クラウド通知リレーを「System_Ext、内部の関係型データベースストレージと外部のトラッキングマイクロサービスをマッピングし、明示的なテックスタックパラメータを使用して通信パイプラインを固定します。

Mermaid VPasCodeでMermaidを編集
Mermaid Edit Mermaid in VPasCode 
C4Container
  title "企業向け電子商取引プラットフォームのコンテナ設計図"

  Person(customer, "オンラインショッパー", "カタログアイテムを閲覧し、商品をデジタルカートに追加する。")
  System_Ext(payment_gateway, "Stripe APIサービス", "第三者のクレジットカード保管庫および処理エンジン。")

  System_Boundary(ecommerce_scope, "電子商取引コア境界") {
    Container(frontend_app, "ストアフロントWebアプリ", "Next.js, React", "静的アセットを配信し、ユーザーのカートセッションを処理する。")
    Container(checkout_service, "チェックアウトマイクロサービス", "Node.js, Express", "ショッピングカートのワークフローを処理し、税額を計算する。")
    ContainerDb(order_db, "注文台帳データベース", "PostgreSQL", "履歴取引行とセキュアな台帳記録を保存する。")
  }

  %% アーキテクチャ間の相互作用経路
  Rel(customer, frontend_app, "製品を閲覧し、注文を出すために使用", "HTTPS/ブラウザ")
  Rel_Down(frontend_app, checkout_service, "ショッピングペイロード取引を送信", "JSON/REST API")
  
  Rel_Right(checkout_service, order_db, "トランザクションステートを内部に永続化", "SQL/JDBC接続")
  Rel_Left(checkout_service, payment_gateway, "トークン化された課金呼び出しを承認", "セキュアなTLS/HTTPS API")
Edit Mermaid in VPasCode
VPasCodeでMermaidを編集

一般的な構文の落とし穴とシステム制約

ソフトウェアフレームワーク向けにクリーンなC4マップをコンパイルする際は、図の破綻を防ぐために以下の実行パラメータに注意してください：

  • コンマ区切りのフォーマット：ほとんどすべての他のMermaidスキーマとは異なり、C4マクロはパラメータの間に厳密なコンマが必要です：Person(id, "ラベル", "説明")区切りのコンマを忘れると、レイアウトビルダーが完全にクラッシュします。
  • 予約済みラベルのクォーテーション：マクロ内の表示フィールド、テックタグ、説明ブロックは*必ず*明確なダブルクォーテーションで囲む必要があります。クォーテーションなしでテキストをフィールドに直接挿入すると、図の破綻を引き起こすパースエラーが発生します。
  • 境界のネスト順序： マクロ内に要素をラップする際は、System_Boundary または Enterprise_Boundary ブロック内では、標準の波かっこ「{}」を使用して、ワークスペースの内容を明示的にクリアする必要があります。{ }境界のカッコを空けたり、正しく対応させなかったりすると、レンダリングレイアウトが破綻します。
  • 動的エイリアスのインスタンス化： エイリアス識別子に対して関係性（Rel）を、上部の要素マクロブロックによって明示的に初期化されていないエイリアス識別子に描くことはできません。宣言の流れを常に上から下へ順次進行させるようにしてください。
上部へスクロール