C4 System Context図：実例で学ぶ完全ガイド - Archyl Blog

System Context図はC4モデルのレベル1であり、チームが作成できる最も重要なアーキテクチャ図です。本ガイドでは、C4のコンテキスト図に何を含めるべきか、完全なコンテキスト図の実例、そして手作業またはコードから生成する方法を解説します。

C4 System Context図：実例で学ぶ完全ガイド

もしアーキテクチャ図を1枚だけ描くなら、System Context図にしてください。これはC4モデルの入口であり、誰もがトレーニングなしで読める図であり、システムが実際に何をするのかについての認識の食い違いを最も素早くあぶり出す図です。

それにもかかわらず、ほとんどのチームはこれを間違えます。データベースやマイクロサービス、Kubernetesクラスタを詰め込みすぎて、「コンテキスト」図が判読不能なインフラマップになってしまうのです。あるいは、これを完全に飛ばしていきなりコンテナ図に進み、技術に明るくないステークホルダーに理解できるものを何も残さないのです。

本ガイドはC4モデルのレベル1を深掘りします。System Context図とは何か、そこに何を含めるべきか（そして何を含めるべきでないか）、完全な実例、ほとんどのコンテキスト図を台無しにする間違い、そして手作業またはコードベースからの生成によってコンテキスト図を作成するステップバイステップのプロセスを扱います。C4モデルそのものが初めての方は、まずC4モデルの完全ガイドから始めて、それから戻ってきてください。

System Context図とは？

System Context図は、C4モデルにおける最初かつ最上位の図です。これは1つのソフトウェアシステムを単一のボックスとして示し、単一の問いに答えます。このシステムはその環境の中にどう位置づけられるのか？

用語集の定義が述べているように、System Context図は、記述対象のシステムと相互作用する人々や外部システムに焦点を当て、内部構造を意図的に省略します。その目的はスコープを確立することです。誰がシステムを使うのか、どのシステムに依存しているのか、どのシステムがそれに依存しているのか。

コンテキスト図に登場する要素は3種類であり、その3種類だけです。

  1. あなたのソフトウェアシステム — 中央に1つのボックス。そのサービスでもデータベースでもなく、1つのボックスです。
  2. 人々（People） — システムと相互作用するユーザー、ロール、ペルソナ。「顧客」「管理者」「サポート担当者」など。
  3. 外部ソフトウェアシステム — あなたのシステムが通信するが、あなたのチームが所有していないシステム。決済ゲートウェイ、メールプロバイダー、レガシーERP、IDプロバイダーなど。

それらをつなぐのが**関係（relationships）**です。誰が何をするのかを記述したラベル付きの矢印です。「注文を行う」「決済リクエストを送信する」「配送状況の更新を受信する」など。

これが語彙のすべてです。システム、人々、外部システムを表すボックスと、関係を表す矢印。この図の規律は、何を省くかにあります。

オーディエンスは誰か？

System Context図は、4つのC4レベルの中でも特異な存在です。なぜなら、全員のために設計されているからです。コードを一行も読まない人々も含めて。

  • 技術に明るくないステークホルダー。 プロダクトマネージャー、CEO、コンプライアンス担当者は、コンテキスト図を見て、システムの目的、ユーザー、サードパーティ依存関係を1分以内に理解できます。
  • 新しいチームメンバー。 新しいエンジニアがあなたのフォルダ構成を学ぶ前に、まずシステムの境界を学ぶべきです。コンテキスト図はオンボーディングのスライド1枚目です。
  • アーキテクトとセキュリティレビュアー。 システム境界を越えるすべての矢印は、統合ポイントであり、データフローであり、潜在的な攻撃対象領域です。セキュリティとコンプライアンスのレビューは、しばしばここから始まります。
  • 他のチーム。 別のチームが「あなたのシステムは課金APIを直接呼び出しますか？」と尋ねたとき、コンテキスト図は会議なしで答えます。

これが、技術選択がここに属さない理由です。コンテキスト図に「PostgreSQL」や「Kafka」と書いた瞬間、あなたはオーディエンスをエンジニアに限定してしまいます。そのためにはコンテナ図があるのです。

コンテキスト図に含めるべきもの（そして含めないもの）

含めるもの

  • スコープ内のシステム — ちょうど1つのボックスで、明確に命名する。
  • すべてのユーザーカテゴリ — 個々の人物ではなく、ロールやペルソナ。顧客と倉庫スタッフがシステムを異なる形で使うなら、それらは2つの別個の人物ボックスです。
  • すべての外部システム依存関係 — 当たり前だと思っているものも含めて。メールサービス、IDプロバイダー、分析プラットフォーム、アーキテクチャ上重要であれば監視スタックも。
  • あなたに依存するシステム — パートナーのシステムがあなたのAPIを利用するなら、それはあなたに向かう矢印とともに図に含まれます。
  • ラベル付きの関係 — すべての矢印には動詞句が必要です。ラベルのない矢印は疑問符です。

除外するもの

  • コンテナ — Webアプリ、APIサービス、データベース、メッセージキューはなし。それらはレベル2です。
  • 技術選択 — 「React」「Go」「PostgreSQL」はなし。コンテキスト図は、スタックを完全に書き換えても変わらないものであるべきです。
  • 外部システムの内部構造 — Stripeは1つのボックスであり、Stripeのアーキテクチャ図ではありません。
  • インフラとデプロイの詳細 — リージョン、クラスタ、ロードバランサーはなし。
  • 個々の機能 — 図は関係を示すものであり、機能一覧ではありません。

簡単なテスト：ある要素を取り除いても、システムと相互作用する誰かや、システムが触れるどの外部システムも変わらないなら、その要素はレベル1に属しません。

完全なコンテキスト図の実例：オンライン決済プラットフォーム

現実的な例を通して見ていきましょう。あなたがPayFlowというオンライン決済プラットフォームをドキュメント化していると想像してください。これは、加盟店が自社のWebサイトでカード決済を受け付けられるようにするものです。

ステップ1：システムを命名する

中央に1つのボックス：PayFlow Payment Platform。一行の説明を付けます。「加盟店がオンラインカード決済を受け付け、管理できるようにする。」

ステップ2：人々を特定する

誰がPayFlowと、どのようなロールで相互作用するでしょうか？

  • 加盟店（Merchant） — 決済ページを設定し、取引を閲覧し、返金をトリガーするビジネスオーナー。
  • エンドカスタマー（End Customer） — PayFlowのチェックアウトを通じて購入の支払いをする買い物客。
  • サポート担当者（Support Agent） — 紛争のあった取引を調査する社内スタッフ。

ステップ3：外部システムを特定する

PayFlowは何に依存し、何がPayFlowに依存するでしょうか？

  • カードネットワーク／アクワイアリングバンク — カード取引を承認し、決済を行う。
  • 不正検知サービス — 取引の不正リスクをスコアリングする。
  • メールサービス — 領収書や通知を送信する。
  • IDプロバイダー — 加盟店のシングルサインオンを処理する。
  • 加盟店ECサイト — PayFlowのチェックアウトを埋め込み、PayFlow APIを利用する加盟店自身のWebサイト。
  • 会計プラットフォーム — 加盟店の経理用に決済レポートを受け取る。

ステップ4：関係を描く

要素と関係の完全なリストは次のようになります。

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

合計10個の要素：1つのシステム、3人の人々、6つの外部システム。すべての矢印に動詞句があります。サービス、データベース、キュー、言語への言及は一切ありません。それでも、この図を読む人は誰でも、PayFlowが何であり、誰が使い、何に依存しているのかを理解できます。

この図が即座に可視化するものに注目してください。

  • コンプライアンスの対象範囲。 図上のカードネットワークと不正検知は、セキュリティレビュアーにPCI関連データがどこを流れるかを正確に伝えます。
  • ベンダーリスク。 6つの外部依存関係はそれぞれ、潜在的な障害点であり、契約交渉の対象です。
  • 双方向の境界。 加盟店のECサイトはPayFlowに向かって呼び出します。このシステムは単に他のサービスの利用者であるだけでなく、他者にとっての依存先でもあるのです。

これこそが、コンテキスト図が始めるために作られた種類の会話です。

System Context図でよくある間違い

間違い1：詳細が多すぎる

最もよくある失敗です。図はきれいに始まりますが、誰かが「メインのデータベースだけ」を追加し、次にAPIゲートウェイ、次に3つのコアマイクロサービスを追加し、1ヶ月以内にそれはコンテキスト図の名を着たコンテナ図になります。解決策は容赦ないものです。あなたのシステムは1つのボックスです。内部を見せたいという衝動を感じたら、それはこの図を過負荷にするのではなく、別個のリンクされたビューとしてコンテナ図を作成すべきというシグナルです。

間違い2：外部依存関係の欠落

チームは決まって、退屈だと思っている依存関係を忘れます。メールプロバイダー、SMSゲートウェイ、IDプロバイダー、CDN、フィーチャーフラグサービス。しかし「退屈な」依存関係こそが、現実の障害や現実のベンダーロックインを引き起こします。設定ファイルと環境変数を確認してください。たいていすべてのAPIキーは、図に属する外部システムに対応しています。

間違い3：抽象度レベルの混在

「Customer → Web App → Orders API → PostgreSQL → Stripe」を示す図は、人物、2つのコンテナ、データベース、外部システムを1つのフラットなビューに混在させています。読者はあなたのシステム境界がどこにあるのか分かりません。各C4図はちょうど1つのズームレベルに存在すべきです。C4モデルの階層の要点は、図の間でズームインするのであって、決して図の中ではないということです。

間違い4：ラベルのない、または曖昧な関係

「Uses（使う）」は関係ラベルではありません。すべてがすべてを「使う」からです。実際に何が起きるのかを書いてください。「経由で注文を送信する」「からWebhookイベントを受信する」「に対して認証する」。ラベルこそが、図の情報のほとんどが宿る場所です。

間違い5：一度描いて二度と更新しない

去年移行したはずのレガシーCRMをいまだに示している2023年のコンテキスト図は、積極的に誤解を招きます。コンテキスト図は下位レベルの図よりも変更頻度は低いですが、それでも変わります。新しいベンダー統合のたび、廃止されたパートナーAPIのたびに。図をキックオフの成果物ではなく、生きたドキュメントとして扱ってください。

System Context図の作り方：ステップバイステップ

手作業のアプローチ

  1. システムを命名し記述する。 一文で。何を、誰のためにするのか？
  2. ユーザーロールを列挙する。 システムと相互作用するすべての異なるペルソナをブレインストーミングする。同じように相互作用するロールは統合し、そうでないものは分割する。
  3. 外部システムを列挙する。 統合、APIキー、Webhook、スケジュールされたエクスポートを確認する。あなたが呼び出すシステムだけでなく、あなたを呼び出すシステムも含める。
  4. 関係を描く。 意味のある相互作用ごとに1本の矢印を、それぞれ動詞句でラベル付けする。方向は主導権に従う。誰が相互作用を開始するのか？
  5. チームでレビューする。 これが最も価値の高いステップです。30分のレビューは確実に意見の食い違いをあぶり出します。「待って、まだあのサービスを呼んでる？」「いつからパートナーが直接APIを叩くようになった？」これらの議論こそが成果物です。
  6. 人々が見つけられる場所に公開する — 誰も訪れないwikiページに埋もれさせないこと。

描画そのものはどんなツールでも構いません。ホワイトボード、diagrams.net、Structurizr、C4拡張付きのPlantUML。ボトルネックは決して描画ではありませんでした。それはステップ2、3、5であり、結果を時間とともに正確に保つことです。

自動化アプローチ：Archylでコンテキスト図を生成する

ここでArchylは描画ツールとは異なる道を進みます。白紙のキャンバスから始める代わりに、リポジトリを接続してAIディスカバリを実行します。Archylはコード構造、設定ファイル、依存関係グラフを分析し、C4モデルの草案を提案します。システム、外部依存関係、コンテナ、コンポーネント、そしてそれらの間の関係です。各提案をレビューし、受け入れるか調整すると、System Contextビューがモデルから自動的にレンダリングされます。

図が手作業で描かれるのではなくモデルから生成されるため、次の2つが帰結します。

  • レベルがつながったままになる。 コンテキスト図のシステムボックスは、コンテナビューのためにドリルダウンするのと同じエンティティです。図の間でのコピー＆ペーストのズレがありません。
  • 陳腐化が測定可能になる。 Archylのドリフト検知は、ドキュメント化されたアーキテクチャを、コードベースに実際に存在するものと継続的に比較します。統合が削除されたりサービスがリネームされたりすると、混乱した新入社員からではなく、ドリフトスコアから気づけます。

バージョン管理の中に存在するドキュメントを好むなら、ArchylはArchitecture as Codeのワークフローもサポートします。C4モデルをYAMLで定義し、コードと一緒にコミットし、その定義から図をレンダリングさせるのです。

コンテキストからコンテナへ

System Context図は境界を設定し、次のレベルはそのボックスを開きます。コンテキスト図が安定したら、自然な次のステップはコンテナ図です。これはレベル2のビューで、システム内部のデプロイ可能なユニット（Webアプリ、API、データベース、ブローカー）と、それらがどう通信するかを示します。詳細はC4コンテナ図ガイドで扱っています。

この進行が重要です。コンテキスト図を飛ばしてレベル2から始めるチームは、境界の曖昧なコンテナ図を作りがちです。システムがどこで終わるのかを誰も合意しなかったため、外部システムが内部サービスと混ざってしまうのです。

FAQ

System Context図とContainer図の違いは何ですか？

コンテキスト図（レベル1）はシステムを単一のボックスとして示し、その環境、つまりユーザーと外部システムに焦点を当てます。コンテナ図（レベル2）はそのボックスの内部にズームインし、デプロイ可能なユニット（Webアプリ、サービス、データベース）とその技術選択を示します。コンテキストは「このシステムは何と相互作用するか？」に答え、コンテナは「このシステムは何で構成されているか？」に答えます。

コンテキスト図には要素がいくつあるべきですか？

厳密なルールはありませんが、健全なコンテキスト図の多くは、1つのシステム、2〜5のユーザーロール、3〜10の外部システムを持ちます。15や20の要素を超えるなら、システム境界が広すぎるか、あるいは企業全体のランドスケープをドキュメント化しているかのどちらかです。後者の場合は、C4のSystem Landscape図（1つのビューに複数のシステム）の方が適しています。

データベースはSystem Context図に登場すべきですか？

いいえ。データベースがあなたのシステムに属する限り、それは内部の詳細であり、コンテナレベルで登場します。例外は、あなたのシステムが直接読み取る、別のチームやベンダーが運用するデータベースです。それは実質的に外部システムであり、外部システムとして登場できます。

C4のコンテキスト図は、UMLやデータフローのコンテキスト図と同じですか？

概念的には親戚です。「コンテキスト図」（1つのシステムとその環境）というアイデアはC4より前から存在し、構造化分析やUMLの実践にもあります。C4版が際立っているのは、その階層の中での位置づけです。その上のすべての要素が次のレベルへと分解でき、独立した一枚絵ではなくナビゲート可能なマップを与えてくれます。

System Context図を作成する準備はできましたか？Archylを無料で試して、リポジトリから直接C4モデルを生成しましょう。あるいは読み進めてください：C4モデルとは？完全ガイド | C4コンテナ図ガイド | 用語集のSystem Context図。