Build C4 System Context Diagrams with PlantUML

ソフトウェアシステムを設計する際、技術者および非技術者のステークホルダー双方に対して高レベルの境界を明確に伝えることは不可欠です。このマスタークラスチュートリアルでは、無料の「VPasCode」エディタ内で、PlantUML を使用してゼロからプロフェッショナルな C4 システムコンテキスト図を構築する方法を詳しく解説します。

なぜ C4 モデルに「図形をコードとして記述する」アプローチを採用すべきなのか？

従来のドラッグ＆ドロップ式の描画ツールは、アーキテクチャが変化するたびに、ボックスの位置ずれ、一貫性のないスタイル、そして面倒な手動更新につながることがよくあります。”図形をコードとして記述するツール”を活用することで、図形をコードとして記述するツール”（例：無料の PlantUML エディタ）を使用すれば、ドキュメントはコードと同期され、バージョン管理が可能になり、クリーンな状態を維持できます。のような無料の PlantUML エディタを使用することで、ドキュメントはコードと同期され、バージョン管理が可能になり、クリーンな状態を維持できます。”VPasCode”を使用すれば、リアルタイムレンダリングと自動フォーマット検出機能により、ソフトウェアアーキテクチャの可視化が極めて容易になります。VPasCode”、リアルタイムレンダリングと自動フォーマット検出機能により、ソフトウェアアーキテクチャの可視化が極めて容易になります。

マスタークラスケーススタディ：オンライン Grocery Store（食料品店）のアーキテクチャ

堅牢なシステムコンテキスト図の構造方法をデモンストレーションするために、オンライン食料品店プラットフォームを見てみましょう。このアーキテクチャでは、エンドユーザー、外部の配送ドライバー、コアとなる食料品システム、および決済ゲートウェイや物流プロバイダーなどのサードパーティサービスを含める必要があります。

以下に、ステップバイステップで解説していく完全な PlantUML ソースコードを示します：

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
skinparam vpDiagramType C4modelSystemContextDiagram

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

title オンライン食料品店のシステムコンテキスト図

Person(customer, "顧客", "店舗を閲覧し、食料品を注文し、配送を予約する")
Person_Ext(driver, "配送ドライバー", "顧客に注文を配送する")

Enterprise_Boundary(grocery_co, "オンライン食料品店") {
  System(grocery_system, "オンライン食料品店システム", "顧客がオンラインで食料品を注文し、納品を管理できるようにする")
}

System_Ext(payment, "決済ゲートウェイ", "カードおよびデジタルウォレットの決済を処理する")
System_Ext(shipping, "物流プロバイダー", "配送ルートを計画し、ドライバーのスケジュールを管理する")

Rel(customer, grocery_system, "商品を閲覧し注文を出す", "HTTPS")
Rel(grocery_system, payment, "決済を処理する", "HTTPS/API")
Rel(grocery_system, shipping, "配送ジョブを作成する", "HTTPS/API")
Rel(driver, grocery_system, "配送割り当てを表示する", "HTTPS")

@enduml

コードのステップバイステップ解説

1. 基盤環境のセットアップ

まず、標準的な PlantUML タグでスクリプトを初期化し、公式の C4-PlantUML 標準ライブラリマクロをインポートすることから始めます。”C4_Context.puml”を参照することで、システムコンテキスト図に特化したセマンティック要素を解放します。C4_Context.puml"、システムコンテキスト図に特化したセマンティック要素を解放します。

ライブラリのインクルード： !include .../C4_Context.pumlは、人、システム、境界に関する標準的な形状、色、およびスタイルルールを読み込みます。
図形のタイプ指定とレイアウト：“skinparam vpDiagramType C4modelSystemContextDiagram”を設定することで、skinparam vpDiagramType C4modelSystemContextDiagram"が”VPasCode”内で適切に統合されることを保証し、VPasCode”、LAYOUT_TOP_DOWN()は、視覚的な階層構造を上部から下部へきれいに整理します。また、私はLAYOUT_WITH_LEGEND()キャンバスの右下に便利なリファレンスガイドを自動的に生成するために使用します。

2. アクターとユーザーの定義

次に、エコシステムと相互作用する人間のアクターを定義する必要があります。特定のC4マクロを使用して、標準的なシステムユーザーと外部エンティティを区別します：

コアユーザー： 以下のマクロを使用して主要なユーザーを作成します：Person(customer, "Customer", ...)これは、注文を開始し、在庫を閲覧するユーザーを表します。
外部アクター： 以下のマクロを使用して配送ドライバーを定義します：Person_Ext(driver, "Delivery Driver", ...)これは、彼らが私たちの履行フローと相互作用する一方で、コアの内部セキュリティ境界の外に存在することを強調するために使用します。

3. 組織境界とコアシステムの確立

アーキテクチャの明確さには明確な境界が必要です。当社が所有するものと外部ベンダーに依存するものをカプセル化するために、エンタープライズ境界を確立します：

エンタープライズ境界： 以下のマクロを使用して：Enterprise_Boundary(grocery_co, "Online Grocery Store")内部インフラストラクチャを視覚的にグループ化する点線のコンテナボックスが作成されます。
内部システム： この境界内に、以下のマクロを使用して主要なソフトウェア資産を配置します：System(grocery_system, "Online Grocery Store System", ...).

4. 外部システムの統合

現代のeコマースプラットフォームが孤立して動作することはありません。エンタープライズ境界の外にある外部依存関係を、専用の外部システムマクロを使用して定義します：

支払い処理： System_Ext(payment, "Payment Gateway", ...)これは第三者による金融取引を表します。
物流と配送： System_Ext(shipping, "Logistics Provider", ...)これはルート計画とドライバーの割り当てを処理します。

5. リレーションシップとプロトコルのマッピング

アーキテクチャを統合するために、私は以下のRel()マクロを使用して、双方向の相互作用と通信プロトコルをマッピングします。

顧客フロー： Rel(customer, grocery_system, "Browses products and places orders", "HTTPS")は、ユーザーがコアプラットフォームにどのように安全に接続するかを示しています。
バックエンド統合：私は、支払い処理や配送プロバイダーなどのバックエンド依存関係を、明確なプロトコルラベル（"HTTPS/API"）を使用して、エンジニアに即座に技術的な文脈を提供します。