C4図
出典: C4モデル公式サイト https://c4model.com/。C4図を作成、レビュー、説明する際には、以下のルールを適用してください。出力に散文(ADR、ドキュメント、PR説明)が含まれる場合は、`writing` スキルも読み込んでください。
1. 目的
C4は、コンテキスト、コンテナ、コンポーネント、コードの4つのズームレベルで構成される「コードの地図」のセットです。Simon Brown氏が、UMLと4+1ビューモデルに触発されて作成したもので、アドホックなボックス・アンド・ライン図を置き換えることを目的としています。C4が修正する典型的な問題: 凡例がない、抽象度が混在している、ラベルのない矢印、技術の欠落、「ビジネスロジック」などの曖昧なラベル。
C4は表記法やツールに依存しません。重要なのは、以下の抽象化とルールであり、形状ではありません。
2. 抽象化
階層: 人物 -> ソフトウェアシステム -> コンテナ -> コンポーネント -> コード。各レベルは、上のレベルの1つの要素にズームインします。
| 抽象化 | 定義 | 例 |
|---|---|---|
| 人物 | システムの人間のユーザー、アクター、ロール、ペルソナ | 顧客、サポートエージェント、管理者 |
| ソフトウェアシステム | 最も高い抽象レベル。ユーザーに価値を提供する。通常、1つのチームが所有・構築する。プロダクトドメイン、境界づけられたコンテキスト、トライブ、スクワッドではない | チケットプラットフォーム、支払いシステム |
| コンテナ | ソフトウェアシステム内の、独立して実行/デプロイ可能なアプリケーションまたはデータストア | サーバーサイドWebアプリ、SPA、デスクトップアプリ、モバイルアプリ、サーバーレス関数、バッチ/コンソールアプリ、マイクロサービスAPI、データベーススキーマ、S3/ブロブストア、CDN、ファイルシステム、シェルスクリプト |
| コンポーネント | コンテナ内の、明確に定義されたインターフェースの背後にある関連機能のグループ。個別にデプロイ可能ではない: コンテナのすべてのコンポーネントは1つのプロセス空間を共有する | OrderController、PaymentService、EmailSender |
| コード | コンポーネント内のクラス、インターフェース、関数、またはDBテーブル | class OrderValidator、orders テーブル |
コンテナのルール (C4 FAQ)
- C4のコンテナはDockerではありません。 パッケージング方法に関わらず、実行可能/デプロイ可能なアプリケーションまたはデータストアのことです。
- サーバーレンダリングされたHTMLアプリは1つのコンテナです。サーバーとSPAまたはモバイルクライアントは、リモートAPIを介して通信する2つのコンテナです。
- JAR、DLL、アセンブリ、モジュールはコンテナではありません。これらはコンテナ内のコードを整理するものです。
- 管理されたデータサービス(S3、RDS、CDN)は、バケットやスキーマを所有または制御している場合、システム境界内のコンテナです。外部システムではありません。
コンポーネントのルール
- コンポーネントはフォルダ、パッケージ、JARではありません。インターフェースを持つ機能的なグループです。
- コンポーネントは個別にデプロイ可能ではありません。個別にデプロイされる場合は、コンテナです。
用語の適応
チームは、図またはそのドキュメントで用語を明示的に定義する場合、言語に固有の名前(関数型コードの Module や Function など)を使用しても構いません。各レベルが厳密に定義されていない限り、余分な抽象化レベルを発明しないでください。
3. 特別なモデリングパターン
キューとトピック
- 間違い: すべてのサービスが接続された、中央に1つの巨大な「メッセージバス」コンテナ(ハブアンドスポーク)。誰が何を生成し、誰が何を消費するかが不明になります。
- オプション1 (推奨): 各キューまたはトピックを独立したコンテナ(メッセージデータストア)としてモデル化します。プロデューサーが書き込み、コンシューマーが読み取り/サブスクライブします。
- オプション2: 直接的なポイントツーポイント結合の場合、キューボックスを省略し、関係に
「キュー orders [AMQP] 経由で注文イベントを公開」とラベル付けします。必要に応じて、これらの線をHTTP呼び出しとは異なるスタイルにします(凡例で説明)。
例: Order API --「OrderPlaced を [Kafka] に公開」--> [(orders topic)] --「OrderPlaced を [Kafka] から読み取り」--> Fulfilment Worker.
マイクロサービス (コンウェイの法則ルール)
- 1つのチームがソフトウェアシステム全体を所有する: 各マイクロサービスを、そのシステム境界内のコンテナグループ(APIコンテナと、それ自体のデータベーススキーマコンテナ、または単一のステートレスLambdaコンテナ)としてモデル化します。
- 別々のチームが各サービスを所有する: 独立して所有される各サービスを、独自のシステムコンテキスト図とコンテナ図を持つ独自のソフトウェアシステムに昇格させます。システム境界を越えて、キュー/トピックの所有権を明示的に示します。
4. 図のカタログ
コアの静的レベル
| レベル | 図 | 推奨 | 範囲 | 対象読者 | 表示/省略 |
|---|---|---|---|---|---|
| 1 | システムコンテキスト | はい | 1つのソフトウェアシステム | 技術者および非技術者 | システムの周囲の人物と外部システム。低レベルの技術やプロトコルは省略 |
| 2 | コンテナ | はい | 1つのソフトウェアシステム | 技術者、運用 | 主要な技術選択とプロセス間プロトコル。クラスタリング、ロードバランサー、フェイルオーバーは省略 |
| 3 | コンポーネント | いいえ: 明確な価値が付加される場合のみ、理想的には自動生成 | 1つのコンテナ | アーキテクト、開発者 | 1つのコンテナ内のコンポーネントとそれらの相互作用 |
| 4 | コード | いいえ: IDEでオンデマンド生成 | 1つのコンポーネント | 開発者 | UMLクラス図またはERD |
補助図
| 図 | 推奨 | 用途 |
|---|---|---|
| システムランドスケープ | はい、組織やポートフォリオ向け | すべてのシステムと人物のエンタープライズまたは部門マップ。単一のフォーカスシステムがないコンテキスト図 |
| ダイナミック | いいえ: 控えめに使用 | 複雑なランタイムコラボレーション。番号付きコラボレーションスタイルまたはUMLシーケンススタイル |
| デプロイメント | はい | 1つの環境(本番、ステージング、開発)。システム/コンテナインスタンスを含むネストされたデプロイメントノード(物理、VM、Docker、Kubernetes、ランタイム)、およびインフラストラクチャノード(DNS、ロードバランサー、ファイアウォール) |
互換性
- arc42: コンテキストとスコープ -> L1; ビルディングブロックレベル1 -> L2; ビルディングブロックレベル2 -> L3; ビルディングブロックレベル3 -> L4。
- UML: ワークフロー、ステートマシン、データモデルについては、C4をUMLステート図、シーケンス図、ERDで補完します。
スケーリングルール
図が乱雑になった場合は、1つのキャンバスに何十ものボックスを詰め込まないでください。同じ抽象レベルで、ビジネス領域、境界づけられたコンテキスト、機能、または単一サービスフォーカス(フォーカスサービスとそのインバウンド/アウトバウンドネイバー)で分割します。
5. 表記規則
図
- タイトルには図の種類と範囲を記載:
支払いチェックアウトシステムのコンテナ図。 - 形状、色、境界線、線種、矢印、頭字語を説明する凡例を必ず含める。
- 厳密な抽象化の純度を維持: 抽象化レベルを決して混在させない(例: L2コンテナ図に
コンポーネントボックスを入れない)。また、L1システムコンテキスト図にプロトコルや内部実装手順([HTTPS]、masked packet、tool_runner)を決して入れない。 - 競合するアーキテクチャや過去のアーキテクチャを比較する場合は、境界タイトルを明示的にラベル付けする(
オプションA (廃止)vs.オプションB (現行))。要件や前提が変更されるたびに、ドキュメント内のすべての図を更新する。
要素
- 名前、明示的な要素タイプ(
人物、ソフトウェアシステム、コンテナ、コンポーネント、データベース、デプロイメントノード)、および簡潔な責務の説明。 - すべてのコンテナ、コンポーネント、デプロイメントノードに明示的な技術を記載。
関係
- 単方向矢印のみ。
<-->は絶対に使用しない。データが双方向に流れる場合は、開始側の方向を示し、ラベルで応答を説明する。 - 具体的な能動的動詞のラベル。単なる「使用する」は避ける。
に注文を送信する、から座席マップを読み取ると記述する。 - コンテナ間の関係にはプロトコル/技術を記載:
[JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。
6. MarkdownでのMermaid
デフォルトは flowchart (flowchart TB または LR)。Mermaidネイティブの C4Context/C4Container は使用しないでください。ネイティブC4構文は実験的であり、Markdownビューアでレンダリングに失敗することがよくあります。ユーザーが明示的に要求し、レンダラーのサポートを確認した場合にのみ出力します。
フローチャートの規則:
- システム境界(コンテナ/コンポーネント)またはデプロイメントノードには
subgraphを使用。 - データベース、データストア、キュー、トピックには
[(...)]を使用。 - 引用符で囲まれたHTMLラベル:
"<b>名前</b><br/>«コンテナ: 技術»<br/>簡単な責務"。 - 引用符で囲まれたラベルを持つ矢印:
A -->|"アクション [プロトコル]"| B。 - 要素タイプごとに1つの
classDefを一貫して適用。 - 色、円筒形状、または複数の線種を使用する場合は、コンパクトな
凡例サブグラフ(接続されていないノード。Dagreが上部に配置する場合、不可視のbottomNode ~~~ 凡例リンクで下部に固定)が必須。タイトルは見出しとして、またはコードブロックの真上のTitle: ...行として配置。 - ダイナミック図:
sequenceDiagram、または番号付き矢印ラベル(1. 注文を送信 [JSON/HTTPS])を持つflowchart。 - デプロイメント図:
flowchart内のネストされたsubgraph。 - 括弧、角括弧、コロンを含むラベルは常に引用符で囲む。
sequenceDiagramまたはstateDiagram-v2ラベル内にエスケープされていないセミコロン (;) を決して入れない(Mermaidは;をステートメントターミネータとして扱い、残りのテキストを無意味なステートまたはパースエラーに分割します)。sequenceDiagram内の長いNoteブロックは<br/>でラップし、テキストがビューポートの端でクリップされないようにする。
テンプレート: L1 システムコンテキスト
タイトル: チケットプラットフォームのシステムコンテキスト図
flowchart TB
customer["<b>顧客</b><br/>«人物»<br/>イベントのチケットを購入する"]
ticketing["<b>チケットプラットフォーム</b><br/>«ソフトウェアシステム»<br/>顧客がイベントを閲覧し、チケットを購入できるようにする"]
payments["<b>決済プロバイダー</b><br/>«ソフトウェアシステム、外部»<br/>カードに請求する"]
email["<b>メールサービス</b><br/>«ソフトウェアシステム、外部»<br/>確認メールを配信する"]
customer -->|"を使用してイベントを閲覧し、チケットを購入する"| ticketing
ticketing -->|"からカード請求を要求する"| payments
ticketing -->|"を使用して確認メールを送信する"| email
email -->|"に確認メールを配信する"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph 凡例
direction LR
l1["人物"]:::person
l2["ソフトウェアシステム (スコープ内)"]:::system
l3["ソフトウェアシステム (外部)"]:::external
end
テンプレート: L2 コンテナ(キューコンテナ付き)
タイトル: チケットプラットフォームのコンテナ図
flowchart TB
customer["<b>顧客</b><br/>«人物»<br/>イベントのチケットを購入する"]
payments["<b>決済プロバイダー</b><br/>«ソフトウェアシステム、外部»<br/>カードに請求する"]
subgraph boundary["チケットプラットフォーム [ソフトウェアシステム]"]
spa["<b>Webアプリ</b><br/>«コンテナ: React SPA»<br/>イベント閲覧とチェックアウトUI"]
api["<b>注文API</b><br/>«コンテナ: Java, Spring Boot»<br/>注文を検証し、発行する"]
db[("<b>注文DB</b><br/>«コンテナ: PostgreSQL»<br/>注文とチケットを保存する")]
topic[("<b>注文トピック</b><br/>«コンテナ: Kafkaトピック»<br/>OrderPlacedイベント")]
worker["<b>フルフィルメントワーカー</b><br/>«コンテナ: Python»<br/>チケットを発行し、メールを送信する"]
end
customer -->|"を使用して閲覧および購入する [HTTPS]"| spa
spa -->|"に注文を送信する [JSON/HTTPS]"| api
api -->|"に注文を書き込む [SQL/TCP]"| db
api -->|"OrderPlaced を公開する [Kafka]"| topic
worker -->|"OrderPlaced を読み取る [Kafka]"| topic
worker -->|"のチケットステータスを更新する [SQL/TCP]"| db
api -->|"からカード請求を要求する [JSON/HTTPS]"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph 凡例
direction LR
l1["人物"]:::person
l2["コンテナ"]:::container
l3[("データストア / キュー / トピック")]:::store
l4["外部システム"]:::external
end
凡例注記: 矢印は開始側からターゲットを指します。ラベルはアクションと [プロトコル] を示します。
テンプレート: デプロイメント
タイトル: チケットプラットフォームのデプロイメント図(本番)
flowchart TB
users["<b>顧客ブラウザ</b><br/>«デプロイメントノード: Chrome»"]
subgraph aws["AWS «デプロイメントノード: クラウド, us-east-1»"]
dns["<b>Route 53</b><br/>«インフラストラクチャノード: DNS»"]
lb["<b>ロードバランサー</b><br/>«インフラストラクチャノード: ALB»"]
subgraph eks["EKS «デプロイメントノード: Kubernetesクラスター»"]
subgraph pod["order-api ポッド «デプロイメントノード: Docker, x3»"]
api["<b>注文API</b><br/>«コンテナインスタンス: Java, Spring Boot»"]
end
end
subgraph rds["RDS «デプロイメントノード: PostgreSQL 16»"]
db[("<b>注文DB</b><br/>«コンテナインスタンス: PostgreSQLスキーマ»")]
end
end
users -->|"を使用してホスト名を解決する [DNS]"| dns
users -->|"にリクエストを送信する [HTTPS]"| lb
lb -->|"にリクエストを転送する [HTTP]"| api
api -->|"で注文を読み書きする [SQL/TCP]"| db
デフォルト以外の色やスタイルを使用する場合は、凡例サブグラフを追加します。
テンプレート: ダイナミック(シーケンス)
タイトル: チケットプラットフォームの注文チェックアウトのダイナミック図(シーケンススタイル)
sequenceDiagram
autonumber
actor customer as 顧客
participant spa as Webアプリ (React SPA)
participant api as 注文API (Spring Boot)
participant payments as 決済プロバイダー
participant db as 注文DB (PostgreSQL)
participant topic as 注文トピック (Kafka)
customer->>spa: 「注文する」をクリック
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: カードに請求 [JSON/HTTPS]
payments-->>api: 支払い承認済み
api->>db: 注文行を挿入 [SQL/TCP]
api->>topic: OrderPlaced を公開 [Kafka]
api-->>spa: 201 Created (注文確認)
spa-->>customer: 注文領収書を表示
最大限のMarkdownビューア互換性を得るために、sequenceDiagram の参加者およびメッセージラベルには、引用符で囲まれていないスラッシュ、セミコロン(;、Mermaidはステートメントターミネータとして解析します)、または生の改行を含めないでください。
7. 図の作成手順
- スコープと目的を定義: 図の種類(システムコンテキスト、コンテナなど)、範囲(どのソフトウェアシステムまたはコンテナが対象か)、および対象読者を決定します。
- すべての要素をリストアップ: 関連する人物、ソフトウェアシステム、コンテナ、コンポーネントを特定します。C4の抽象化ルールに従って正しく分類されていることを確認します。
- 関係を特定: 要素間のすべての相互作用を特定します。方向、ラベル(能動的な動詞を使用)、プロトコル/技術を決定します。
- 図を描画: 選択した表記法(推奨: Mermaidフローチャート)で図を描画します。凡例を含めることを忘れないでください。
- レビューと改善: 図がC4ルール(抽象化の純度、単方向矢印、具体的なラベルなど)に準拠していることを確認します。明確で不要な詳細がないかどうかを確認します。
8. 追加のヒント
- 図はシンプルに保つ: 1つの図に7±2個以上の主要要素を含めないようにします。それ以上の場合は、分割を検討します。
- 一貫性を保つ: 同じプロジェクト/ドキュメント内で、色、形状、凡例のスタイルを一貫して使用します。
- 凡例は常に含める: これは交渉の余地がありません。凡例がないと、図は誤解されやすくなります。
- 図に日付を付ける: 時間の経過とともに変化するアーキテクチャを扱う場合、バージョン管理に役立ちます。
- 最新の状態に保つ: コードベースが進化するにつれて、図を更新します。理想的には、コード駆動の図生成(Structurizr DSL など)を使用します。