ソフトウェアアーキテクチャはしばしば目に見えない。コードやサーバー、エンジニアが行う意思決定の中に存在するが、共有されたメンタルモデルにはほとんど現れない。複雑なシステムについてチームがコミュニケーションする際、言葉だけでは不十分になる。誤解が生じ、境界が明確でない形で技術的負債が蓄積される。これが「C4モデル」が登場する場面である。異なる抽象度のレベルでソフトウェアアーキテクチャを可視化するための標準化された方法を提供する。
C4モデルを使用することで、アーキテクトや開発者は物語を伝える図を描くことができる。すべてのクラスやメソッドでステークホルダーを圧倒するのではなく、C4アプローチは全体像から具体的な論理までズームインする。このガイドでは、実際のシナリオでC4モデルをどう適用するかを検討し、図がその目的である「明確さ」を果たすことを保証する。
🧩 抽象度の4つのレベルを理解する
C4モデルの核となる強みは、4つの明確なレベルにある。各レベルは特定の対象者に対して特定の質問に答える。これらのレベル間を移動することは、カメラのフォーカスを調整するのと似ている。まず広い視野で環境を示し、次に内部機構を詳細に表示する。
1. システムコンテキスト図 🌍
システムコンテキスト図は高レベルの概要図である。ソフトウェアシステムを1つのボックスとして示し、それにやり取りする人々やシステムを描く。これは、プロジェクトの範囲を理解したいステークホルダーに見せる図である。
- 対象者：ビジネス関係者、プロダクトオーナー、新規チームメンバー。
- 注目点：境界と外部との相互作用。
- 主要な要素：
- 対象システム：議論されている主要なソフトウェアアプリケーション。
- 人々：システムとやり取りするユーザー、管理者、または特定の役割。
- システム：外部の第三者サービス（例：決済ゲートウェイ、メールプロバイダー）または他の内部システム。
ここでの関係はデータフローを表す。たとえば、ユーザーがシステムにリクエストを送信し、システムがメールプロバイダーに通知を送信する。内部の詳細は一切なく、境界のみが示される。
2. コンテナ図 📦
境界が設定されると、コンテナ図はズームインする。システムをデプロイメントの明確な単位に分解する。これらはしばしば「コンテナ」と呼ばれるが、Dockerコンテナを指すとは限らない。あらゆる明確な実行環境を表す。
- 対象者：開発者、アーキテクト、DevOpsエンジニア。
- 注目点：技術選択と高レベルのデータフロー。
- 主要な要素：
- コンテナ：Webアプリケーション、モバイルアプリ、データベース、マイクロサービス、バッチ処理。
- 関係性：コンテナを接続するために使用されるプロトコル（例：HTTP、gRPC、SQL）。
- 技術：コンテナ内で使用される特定の言語またはデータベースタイプ（例：Node.js、PostgreSQL）。
この図はテクノロジー・スタックを明確にします。『システムのどの部分を独立してデプロイできるか？』という問いに答えます。また、データの永続化がどこで行われるか、およびサービス間の通信方法を特定するのにも役立ちます。
3. コンポーネント図 🧩
コンテナ内では複雑性が増加します。コンポーネント図は、単一のコンテナ内の主要な構成要素を明らかにします。ここにビジネスロジックが存在します。コードの詳細は抽象化されますが、アーキテクチャ構造は可視化されたままです。
- 対象読者：コア開発者、機能担当者。
- 注目点：内部ロジックと責任範囲。
- 主な要素：
- コンポーネント：特定の機能を実行するクラス、モジュール、またはパッケージ（例：認証、注文処理、レポート作成）。
- インターフェース：コンポーネント同士がどのように相互作用するか（例：API、内部メソッド）。
- フロー：同じコンテナ内のコンポーネント間でのデータ移動。
このレベルは、新規開発者のオンボーディングにとって不可欠です。ソースコードをすぐに読む必要なく、リクエストがアプリケーション内でどのように流れているかを説明します。
4. コード図 📝
最終段階はコード図です。C4モデルは技術的にはコンポーネントまでですが、ときには開発者が特定のクラス構造を見たい場合があります。これは通常、自動生成されるか、特定の複雑なアルゴリズム用に手書きされます。
- 対象読者：特定の機能を実装するエンジニア。
- 注目点：クラス構造とメソッドシグネチャ。
- 主な要素：
- クラス：特定の実装単位。
- メソッド：関数とアクション。
- 属性： データフィールド。
使用は慎重に。静的なコード図は、コードがリファクタリングされた瞬間に古くなることがあります。複雑なアルゴリズムの文書化に適しており、一般的なシステムアーキテクチャの記述には向いていません。
📊 C4のレベルを比較する
違いを明確に可視化するため、以下の比較表を検討してください。これはC4モデルの各段階における明確な目的と対象読者を強調しています。
| レベル | ズームレベル | 主な対象読者 | 回答される主な質問 |
|---|---|---|---|
| システムコンテキスト | マクロ | ステークホルダー | システムとは何か？誰がそれを使用しているのか？ |
| コンテナ | ハイレベル | 開発者 | どのような技術が使用され、それらはどのように接続されているか？ |
| コンポーネント | ミドルレベル | アーキテクトと開発者 | サービス内部の論理はどのように構成されているか？ |
| コード | マイクロ | エンジニア | 具体的なクラス構造は何か？ |
🚀 実際のアーキテクチャシナリオ
理論的な知識は役立ちますが、モデルを実際に適用する場で価値が創出されます。以下の3つの実際のシナリオは、C4モデルが異なるニーズにどのように適応するかを示しています。
シナリオ1：モノリスからマイクロサービスへの移行 🔄
組織が大きなアプリケーションを小さなサービスに分割することを決定する際、失敗のリスクは高くなります。C4モデルはその移行プロセスを可視化するのに役立ちます。
- 現在の状態：モノリスのシステムコンテキスト図を描いてください。すべての外部依存関係を特定してください。
- 目標状態：新しいマイクロサービスを示すコンテナ図を作成してください。どのコンテナがモノリスのどの部分を置き換えるかを定義してください。
- 統合：新しいコンテナがどのように通信するかを文書化してください。システムコンテキスト図が全体のプラットフォームの新しい境界を反映していることを確認してください。
このアプローチにより、「ビッグバン」型の移行を防ぐことができます。コードを書く前に分割を可視化できます。また、新しい2つのサービス間でまだ共有されているデータベースのような通信のボトルネックを早期に浮き彫りにできます。
シナリオ2：新規開発者のオンボーディング 🎓
新しいエンジニアがチームに加わると、しばしば何週間もドキュメントの読解に費やすものです。静的なドキュメントは解読が難しいです。C4図のセットが道筋を提供します。
- 1週目：システムコンテキスト図を提供してください。彼らはユーザーが誰であるか、外部システムが存在するかを学びます。
- 2週目：コンテナ図を提供してください。彼らはテクノロジー・スタック（例：APIを実行する言語）を理解します。
- 3週目：彼らの特定のモジュール用のコンポーネント図を提供してください。コードを書く場所や実装すべきインターフェースを理解します。
この構造化された学習パスにより、生産性に必要な時間が短縮されます。曖昧な口頭説明を、明確な視覚的参照に置き換えます。
シナリオ3：新機能の設計 🛠️
新しい機能のコードを書く前に、チームはしばしばアイデアをスケッチします。C4モデルはこの設計プロセスに厳密さを強いるのです。
- 影響を評価する：この機能は新しいコンテナを必要とするか？それとも既存のコンポーネントに収まるか？
- 境界を定義する：新しいコンテナが必要な場合は、すぐにコンテナ図を更新してください。これにより、既存のサービスに機能が拡大するのを防ぎます。
- ドキュメントを更新する：新しい外部システムが追加された場合（例：新しいアナリティクスプロバイダー）、システムコンテキスト図を更新してください。
コードと並行して図を更新することで、ドキュメントは真実の情報源のまま保たれます。多くのソフトウェアプロジェクトを悩ませる「ドキュメントの劣化」を防ぎます。
🔄 動的図と静的図
ほとんどのC4図は静的なものです。それらは特定の時点での構造を示します。しかし、データの動きを理解することも同様に重要です。動的図は静的図を補完します。
シーケンス図 🕒
これらの図は、時間の経過とともにコンポーネント間の相互作用の順序を示します。複雑なワークフローを理解する上で不可欠です。
- ユースケース： ユーザーが「チェックアウト」をクリックする。次に何が起こるか？
- フロー：ブラウザがリクエストをAPIゲートウェイに送信 → APIゲートウェイが注文サービスにルーティング → 注文サービスが決済サービスを呼び出し → 決済サービスが応答する。
- 利点：遅延の発生ポイントとエラー処理の戦略を強調する。
データフローダイアグラム 🌊
これらはデータがシステム内でどのように入力され、出力され、変換されるかに注目する。セキュリティ監査やデータガバナンスにおいて有用である。
- 使用例：個人識別情報（PII）の追跡。
- フロー：ユーザー情報 → データベース → バックアップシステム → 暗号化レイヤー。
- 利点：機密データが格納され、送信される場所を特定する。
🛡️ メンテナンスのためのベストプラクティス
更新されない図は誤解を招く。図がないよりも悪く、誤った安心感を生むからである。C4図を有用な状態に保つためには、以下の原則に従うべきである。
1. 図をコードとして扱う 📜
図をソースコードと同じリポジトリに保存する。これによりバージョン管理が保証される。コードが変更された場合、図も同じコミットで更新すべきである。これにより単一の真実の源が確保される。
2. 過剰なドキュメント化を避ける 📉
すべてのコンポーネントに図が必要というわけではない。サービスが単純で標準的なパターンに従っている場合、コンポーネント図は不要である可能性がある。複雑さに注目する。理解しにくいか、高いリスクを伴うシステムの部分を文書化する。
3. 一貫した記法を使用する 🎨
全員が同じ記号を使用することを確認する。たとえば、データベースには常に円筒、Webアプリケーションには常に箱を使用する。一貫性があることで、図を読む際の認知負荷が軽減される。C4仕様で定義された標準的な形状に従う。
4. 可能な限り自動化する 🤖
一部の要素は自動的に生成できる。コード図は、静的解析ツールを用いてソースコードから導出できることが多い。これにより、正確性を維持するための手作業が削減される。ただし、上位レベルの図（コンテキスト、コンテナ、コンポーネント）は、アーキテクチャの意図を反映させるために通常、手動での更新が必要である。
🚫 避けるべき一般的な落とし穴
最高の意図を持っていても、チームはC4モデルを適用する際にしばしばつまずく。これらの落とし穴を認識することで、それらを回避できる。
- 詳細が多すぎる：コンポーネント図にすべてのクラスを含めることは目的を無効にする。抽象度を保つこと。すべてのクラスを確認したい場合は、コードレベルを使用する。
- 抽象度の不一致：レベルを混同しない。コンテナ図に個々のコンポーネントを表示するのは、それが重要でない限り避けるべきである。レベルごとに範囲を一貫性を持たせる。
- 関係性を無視する：線のないボックスを描くのは無意味である。ボックス間のデータフローに注目する。矢印がシステムの動作の物語を語る。
- 静的図と動的図の混同: 静的コンテナ図にシーケンスの流れを示そうとしないでください。そのために別途シーケンス図を使用してください。
- セキュリティ境界の無視: システムコンテキスト図では、信頼境界を明確にマークしてください。どの外部システムが信頼されるのか？どのシステムが信頼されないのか？これはセキュリティアーキテクチャにとって極めて重要です。
🔍 視覚的言語と標準
C4モデルは、チーム間での明確な理解を確保するために特定の視覚的言語に依存しています。図作成ツールは任意のものを使用できますが、C4の標準に従うことで、普遍的な理解が保たれます。
形状と色
- 人間: 人間のユーザーまたは役割を表します。
- ソフトウェアシステム: 角が丸い長方形。
- コンテナ: シリンダーまたは角が丸い長方形（コンテナの種類によって異なります）。
- コンポーネント: 単純な長方形。
- データベース: シリンダー。
- クラウド: 外部インフラストラクチャを表すクラウド形状。
関係線
- 実線: 強い依存関係または直接的な接続を示します。
- 破線: より弱い依存関係またはオプションの相互作用を示します。
- 矢印: データの流れの方向を示します。
- ラベル: すべての線には、何のデータが渡されているかを説明するラベルを付ける必要があります（例：「ユーザーID」、「注文データ」）。
📈 大規模組織向けのモデルのスケーラビリティ
大規模な企業では、1つのシステムに複数のコンテキスト図が存在する場合があります。C4モデルは階層構造によって良好にスケーリングできます。
- プラットフォームレベル： 組織内のすべての主要なプラットフォームを示す図。
- サービスレベル： 複数のコンテナを含む各プラットフォームの図。
- 機能レベル： コンテナ内の特定の機能セットを示す図。
ナビゲーションが重要です。図の間にはリンクを設けるべきです。コンポーネント図は、所属するコンテナ図にリンクするべきです。これにより、視聴者が高レベルの戦略から具体的な実装ロジックまでスムーズに移動できるようになります。
🛠️ 開発ワークフローとの統合
アーキテクチャ図は孤立して存在してはいけません。開発ワークフローの一部でなければなりません。
- 設計レビュー：アーキテクチャレビュー会議ではC4図の作成を必須とすること。図を描けないなら、実際に構築するには十分理解していない可能性が高い。
- プルリクエスト： プルリクエストがアーキテクチャを変更する場合、図の更新を含むべきです。これにより、著者がコードの影響を考慮するよう強制されます。
- インシデント対応： サービス停止時にシステムコンテキスト図があると、問題が内部か外部かを特定しやすくなります。どの外部依存関係が失敗したかを把握することで、時間を節約できます。
🔑 主な教訓の要約
C4モデルは箱を描くことだけではありません。コミュニケーションのためのものです。システムを異なるスケールで考えるよう強制します。コンテキスト、コンテナ、コンポーネントのレベルを分けることで、聴衆を混乱させることを避けられます。
- コンテキスト は境界を定義する。
- コンテナ は技術を定義する。
- コンポーネント はロジックを定義する。
- コード は実装を定義する。
適切に適用すれば、これらの図はアーキテクチャ知識の動的なライブラリになります。伝統的な知識への依存を減らし、複雑なシステムを透明にします。レガシーシステムの移行であれ、新しいプラットフォームの構築であれ、C4モデルは成功に必要な構造を提供します。
小さなステップから始めましょう。一つのシステムを選んで、コンテキスト図を描いてください。その後、ズームインします。シンプルに保ち、正確に保ち、何よりも常に最新の状態に保つことが重要です。
