「システム構成図」は、絵でなくコードで書く

構成図はコードから起こす。IceShoreはその新しい形

構成図は重要です#

新しく入ったシステムを理解するとき、最初に開くのは構成図だと思います。どこに入口があって、要求がどこを通って、データがどこに残るのか。文章で読めば数ページかかることが、1枚の図から、すばやく頭に入ります。

構成図が雄弁なのは、関係が形として見えるからです。箱の並びと線のつながりを目で追うだけで、依存の向きと深さが分かります。この速さは、文章では出せません。

人が図を描くと、3つのことが起こります#

まずは、描き手によって読みやすさが変わります。同じシステムでも、人が変われば箱の並べ方も粒度も変わるからです。前任者の図を引き継いだ人が、まず自分の描き方に直すのは珍しくありません。

2つめは、結線の複雑さによる誤解です。要素が増えるほど線は交差します。交差が増えると、どの線がどこへ向かっているのかを目で追いにくく、誤解が生じます。

3つめは、コードの更新に追いつかないことです。デプロイのたびに構成は変わりますが、図は誰かが気づいたときだけ直ります。半年後に見た図が、いま動いているものと同じである保証はありません。

だから、コードから図を起こす取り組みがあります#

誰が起こしても同じ図になり、コードが変われば図も変わる。この考え方に立つ道具は、すでにいくつもあります。

図そのものをテキストで書く道具もあります。PlantUML、Diagrams、Structurizrがそれで、図の記述を版管理に載せられます。ただしこちらは、インフラの定義から図が導かれるわけではありません。インフラを変えても、人が記述を書き直すまで図は変わりません。

私たちも、コードから図を起こすアプローチに賛成です。IceShoreはその一つの形です。

ただし、IceShoreは正確さの先を目指します#

コードから起こした図は、構造については正確です。どのリソースがどのリソースを呼んでいるかは、定義ファイルを読めば判定できるからです。

一方で、読めないものもあります。そのシステムが業務で何をしているか（ユースケース）です。

コードのどこにも「この経路が止まると受付の予約業務が止まる」とは書かれていません。書いてあるのは、どのエンドポイントがどのデータベースを叩くかまでです。業務との関連づけは大抵、担当者の頭の中と、不完全な資料、会議録に埋もれています。

よってIceShoreはその関連づけを注入するための定義言語「ADL（Architecture Description Language）」を使って、構成図を生成します。

そこには、誰が（アクター）、何を（リソース）、どのように使うか（ユースケース）という情報が記述されます。またリソースについては、ADLが既存のプロビジョニングコード（Terraform、CloudFormation、Azure Resource Manager、Google Cloud Deployment Manager、Alibaba Cloud ROS、Serverless Framework）を参照することで表現されます。それらの構造を一から写しとる無駄はありません。構造の出どころは、いま動いているものを作ったそのファイルのままです。ADLが足すのは、その上に載せるユースケースです。

業務との関連づけを載せると、人もAIも影響範囲をたどれます#

業務との関連づけが図に入っていると、「このデータベースを止めたら誰が困るか」に、図をたどるだけで答えが出ます。止まる経路を先頭まで遡れば、その業務と、困る相手が並びます。

同じことを、あなたがお使いのAIでも行えます。図と関連づけがAIに読める形で載っているので、IceShoreに接続したAIは、推測ではなく参照で答えられます。

AIに保守を任せるとき、この関連づけが役立ちます#

生成AIで開発が速くなり、手元のシステムは増えています。増えた分を保守するには、AIの力が必要です。

そのAIに、既存のコードだけを渡しても足りません。既存コードから読み取れるのは構造までで、ユースケースはそこに書かれていないからです。AIに保守を任せるほど、既存コードでは読み切れない、システムと業務の関連性に関する情報を渡す必要が増します。

ADLとは#

IceShoreは、構成図をADL（Architecture Description Language）というテキスト形式で持ちます。言語仕様とスキーマは、Reindeer Technology Pte. Ltd. がApache License 2.0で公開しています。

図の配置は自動です#

ADLに書くのは要素と関係だけで、座標を書く欄がありません。図の配置は描画アルゴリズムが決定します。

つまり、描き手によって図の見え方が変わることも、線の交差を人が手で整えることもありません。ドローツールで手間のかかる作業が、そもそも発生しません。

ADL文書中で宣言が必須なのは、6要素です#

宣言が必須なのは、reindeer、self、info、actors、resources、useCasesの6つです。（reindeerはADL仕様そのもののバージョンで、本執筆時点の公開サンプルでは「2.0.0」です。）

参照の形が決まっているので、AIがたどれます#

要素どうしのつながりは、文字列の参照で表します。例えばユースケースA（Web閲覧）がアクターX（ゲスト）のリクエストで始まり、リソースP（データベース）へのデータ保存で終わるといった形です。

形が決まっているので、参照をたどる処理をAIが書けます。終点は参照の配列なので、どのトラフィックがどのリソースで終わるかを集計できます。

ユースケースが、必須フィールドです#

ここが、システム構造だけを記述するツールとの違いです。先に挙げたツールはどれも、そのリソースが業務で何をしているかを書く欄を必須にしていません。ADLでは、その欄を省くと妥当なファイルになりません。

IceShoreにお使いのAIを繋ぐと、AIが既存の資料からADLを記述できるようにガイドします。よって大きな手間をかけずに、ADLは完成させられます。

なお、AIで記述できた内容は、AIによるシステム理解の投影です。あなたがそれを補正すれば、AIのシステム理解も深まります。

情報の機微も、必須の真偽値です#

infoTypeの定義は、confidentialとprivacyという2つの真偽値を必須で持ちます。各経路はこの定義を参照し、データが残る場合はstoredInfoTypeを別に指定します。

したがって、個人情報が流れる経路と、それが保管されている場所は、2つの参照をたどれば列挙できます。セキュリティ審査のたびに人が作り直していた一覧が、構成図から引けます。

差分を行単位でチェックできます#

テキストなので、変更は行の差分で表示されます。書き出したADLをリポジトリに置けば、構成の変更も既存のコードと同じ手順でレビューできます。

ドローツールのファイルは、開いて見比べるまで何が変わったのか分かりません。ADLでは、変わった行だけが見えます。

ADLは仕様が公開されているので、ご自身のツールにも組み込めます#

定義スキーマはja/reindeer-schema_cds.jsonとen/reindeer-schema_cds.jsonの2本です。必須フィールドは両者で一致していて、違うのは説明文の言語です。

Apache License 2.0なので、社内の道具に組み込んでも、別のサービスから読み書きしても構いません。IceShoreとの契約は要りません。

https://github.com/reindeer-project/ArchitectureDescriptionLanguage

実物を見る#

サンプルの構成図は、登録なしで開けます。

https://app.iceshore.ai/ja/workspace/sample/

お使いのAIを繋いで「診療記録のデータベースを止めたら誰が困るか」と聞けば、この記事で見た参照の連なりを、AIがたどって答えます。