アーキテクチャ図の書き方：ソフトウェアチームのためのステップバイステップガイド

初めてアーキテクチャ図を書くとき、難しいのは箱を描くことではありません。何を描かないかを決めることです。このガイドで扱うのは、ソフトウェアとシステムのアーキテクチャ図、つまりサービス、データベース、キュー、ネットワークゾーン、そしてそれらの間の接続です。初めてのソフトウェアアーキテクチャ図でも、チームで10枚目の図でも、以下の手順に沿えば、読みやすく、最新の状態を保てる図を作れます。

まず読み手と問いを決める

良い図は、ひとつの問いに答えます。「システムのすべて」は問いではなく一覧表です。一覧なら図よりも表のほうが向いています。

描き始める前に、次の2文を書き出してください。

• 読み手は誰か？ 入社したばかりの開発者、オンコールのSRE、セキュリティレビュー担当、プロダクトマネージャー、外部の監査人など。
• どの問いに答えるのか？ 「注文リクエストはどのサービスを通るのか？」「インターネットに公開されているのはどこか？」「リージョン障害時にトラフィックはどこへ流れるのか？」

この2文で図のスコープが決まります。新しく入った開発者と、ネットワークチームとでは、必要な詳細度が違います。1枚で両方に応えようとすると、どちらにも役立たない図になります。

図の種類を選ぶ

問いがはっきりすれば、図の種類はほぼ自然に決まります。出発点としてはC4モデルが便利です。システムをcontext、container、component、codeというズームレベルに分けて捉えます（詳しくは c4model.com）。

迷ったらコンテキスト図から始めてください。システムの境界と外部依存が明確になり、以降の図すべての枠組みになります。

アーキテクチャ図の書き方：ステップごとの手順

1. スコープと境界を決める

図の内側に何があり、外側に何を置くかを書き出します。チームが所有するコンポーネントは境界の内側、決済プロバイダー、IDプロバイダー、他チームのサービスなどの依存先は外側です。外部システムはひとつの箱で表します。その内部構造まで描く必要はありません。

2. コンポーネントを洗い出す

描く前にリストを作ります。サービス、データベース、キュー、キャッシュ、外部API、ユーザーの種類。名前はチームが実際に使っている呼び方にし、リポジトリ名やdeployment名と一致していればなお良いです。一目で把握できないほどリストが長いなら、たいてい図を2枚に分けるべき内容です。

3. 関係はラベル付きの矢印で、向きを明示して描く

ラベルのない線は「何らかの関係がある」としか伝えません。すべての矢印に向きと、少なくともプロトコルと目的の2つの情報を付けます。必要なら同期か非同期かも書き添えます。

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

矢印は呼び出し側から受け手に向けます。レスポンス用に2本目の矢印を引くのはやめましょう。線の数が倍になるだけです。リクエストとレスポンスの順序が重要なら、それはシーケンス図の役割です。

4. フレームでグループ化する

グループは図の2つ目の読み取りレイヤーです。意味のある境界でコンポーネントを囲みます。

• ネットワークゾーン： パブリックサブネット、プライベートサブネット、DMZ、オンプレミスのネットワーク
• Kubernetesのnamespace： payments、platform、observability
• リージョンとアカウント： eu-central-1、us-east-1、本番とステージングのアカウント
• 信頼境界： インターネットからのトラフィックが認証される場所

入れ子にしても構いません（リージョン > VPC > サブネット）。ただし階層が深くなるほど読みにくくなります。

5. 凡例を付ける

色、線種、アイコンに意味があるなら、凡例に書く必要があります。破線は非同期メッセージなのか、赤い枠はPCIの対象範囲なのか。描いた本人には自明でも、半年後に読む人には自明ではありません。

6. タイトル・日付・オーナーを入れる

すべての図の隅に3つの情報を置きます。何を示す図かがわかるタイトル（「Checkout — コンテナ図、本番」）、最終更新日、そしてオーナーのチームです。日付のない図は最新かどうか誰にもわからず、オーナーのいない図は誰も更新しません。

7. 描いていない人にレビューしてもらう

図を描いていない人に見せ、最初に書いた問いを投げかけてください。あなたの説明なしで答えを見つけられれば、その図は機能しています。「ここは実はこういう意味で…」と何度も補足しているなら、その説明を図そのものに書き込みましょう。

よくある失敗

• すべてを1枚に詰め込む。 コンテキスト、デプロイ、ネットワークの詳細が1枚に混在すると、結局どれも読まれません。
• ラベルのない矢印や双方向の矢印。 誰が誰を呼んでいるのかが曖昧になります。インシデント対応中にまさに知りたい情報です。
• 抽象度が混在している。 ある箱が「決済システム」で、隣の箱が「Redisのpod」だと、読み手はスケール感を失います。
• 説明のない色。 凡例にない色は、ただの装飾か、誤解のもとです。
• オーナーも日付もない。 作者のわからないままWikiに置かれた図は、やがて誤情報の発生源になります。

図を最新に保つ

図が役に立つのは、信頼されている間だけです。いくつかの習慣が助けになります。

• 図は対象システムのドキュメントの近くに置き、READMEやrunbookからリンクします。
• アーキテクチャを変えるpull requestのチェックリストに「図は更新したか？」を加えます。
• 大きな変更の前にはリビジョンを残し、「前の四半期はどうだったか？」に答えられるようにします。
• オーナーのチームのカレンダーに、たとえば四半期に一度の定期レビューを入れておきます。

Archboardでソフトウェアアーキテクチャ図を書く

Archboardは、プラットフォームチームやプロダクトチーム向けのクラウド型アーキテクチャワークスペースです。上の手順はどのツールでも使えますが、Archboardでは次のようになります。

1. サインインする。 ログインページからGoogleまたはGitHubアカウントでサインインします。初回サインインでアカウントと組織が作成されます。クレジットカードは不要です。
2. パックを選ぶ。 Archboardには27の組み込みパックと223種類のノードがあります。最初の図なら、たいてい次のパックで足ります。
   • C4 Model： Person、Software System、Container、Component、Database、boundary。コンテキスト図とコンテナ図に。
   • Kubernetes： Namespace（フレームとして描画）、Deployment、Pod、Service、Ingress、ConfigMap、Secret、PVC、HPA、NetworkPolicyなど。
   • Cloud： クラウドインフラ向け。マルチアカウント構成図用のk8s-clusterノードも含まれます。
   • Network： ネットワークゾーンと接続に。
3. ポートをつなぐ。 ノードは汎用の図形ではなく、ポートを持つファーストクラスのノードです。ポートからポートへ接続をドラッグし、プロトコルと目的をラベルに書きます。
4. フレームでグループ化する。 ネットワークゾーンやリージョンにはCoreパックのFrame、namespaceにはKubernetesのNamespace、システム境界にはC4のboundaryを使います。
5. タイトルと凡例を入れる。 キャンバスにMarkdownブロックかTableを置き、タイトル、日付、オーナー、凡例を1か所にまとめます。
6. 共有する。 公開共有リンクをレビュー担当に送ります（Freeプランではリンクにブランド表示が入ります）。ProとEnterpriseでは、iframeでドキュメントサイトに図を埋め込めます。
7. エクスポートする。 SVGまたはPNGでエクスポートできます（Freeでは透かし入り）。ProではJPEG、PDF、アニメーションGIF / WebMも使え、いずれも透かしなしです。図のドキュメントを構造化JSONとしてエクスポートすることもできます。

変更は自動保存され、すべての図にリビジョンが残ります。Free では直近 5 件、Pro では 1 年分、Enterprise では期間の制限なく履歴が残ります。Free にはすべての組み込みパック、3 つのダイアグラム、図ごとに 15 ダイアグラムノードと 150 件のメモ・テキスト・ステッカー・マインドマップのトピックが含まれ、最初のコンテキスト図には十分です。デプロイメントの全体マップを作るなら、Pro で図とノードが無制限になります。詳しくは料金をご覧ください。

始める前にサンプルギャラリーを見てみましょう。公開されているサンプルを開き、この事例を使うで自分のワークスペースにコピーします（ダイアグラム枠に数えられます）。C4 や Kubernetes の詳細は、C4 のユースケースとKubernetes のユースケースのページを参照してください。最初のアイデア出しも同じキャンバスで始められます。Archboard にはアーキテクチャのパックと並んで、付箋やマインドマップもあります。

チェックリストとよくある質問

公開する前に確認しましょう。

• 読み手と問いが書き出されている
• 境界が明確で、外部システムはひとつの箱になっている
• すべての矢印に向きと「プロトコル＋目的」のラベルがある
• グループがネットワークゾーン、namespace、リージョンなど実際の境界を表している
• 凡例、タイトル、日付、オーナーがある
• 描いていない人が問いに答えられた

アーキテクチャ図とフローチャートの違いは何ですか？ アーキテクチャ図は構造を示します。どのコンポーネントがあり、どうつながっているかです。フローチャートはプロセスの手順と分岐点を示します。リクエストの時間的な順序が重要なら、シーケンス図を使ってください。

図は何枚描けばよいですか？ 読み手と問いの組み合わせごとに1枚です。多くのシステムでは、コンテキスト図、コンテナ図、デプロイ図の3枚から始めるのがよいでしょう。

どのツールを使うべきですか？ 描く概念を理解しているツールです。Archboard は Kubernetes、C4、クラウドの概念をポート付きの既製ノードとして提供するので、図が読みやすく、最新の状態を保ちやすくなります。どのツールを選ぶにしても、本当の基準はその図が問いに答えているかどうかです。

無料で始める — 1シート、クレジットカード不要