プロダクトがどのように動いているか最速でざっくり理解する"解体新書"プロジェクト

スペースマーケットに入社してはや半年、ひとつ形になったものがあるので今回はその取り組みを紹介したいと思います。

はじめに

プロダクト開発において、システム構成図は全体のアーキテクチャを理解するための重要なツールです。
どのようなサービス、コンポーネントが存在しているか、システムにおける登場人物がどのような関係性を持っているかを把握しやすくしてくれます。

わたしたちスペースマーケットでは、スペースの検索を行うAPI、スペースに対する予約を行うAPI、ホスト（部屋や物件のオーナー）審査など複数のコンポーネントから構成されるマイクローサービス^[1]で構築されています。

しかし、ユーザーが実際に画面を操作して検索や予約などを行う際に、どのような順序でどのようなサービスが影響し合っているのかを把握するためにはシステム構成図だけでは困難な場合があります。

モチベーション

「どのような順序でどのようなサービスが影響し合っているのか」

この問いに答えてくれる内部のドキュメントを探してみたのですが、開発案件の設計ドキュメントやバッチ処理のフロー図といった個別の資料はあるものの、プロダクト全体のプロセスを把握できるものを見つけることはできませんでした。

なければ作ればいいじゃない。

ということで、

• 自分の理解を深めること
• 新しく入ってきた方のオンボーディングに使えるもの

をモチベーションに、上記で示した課題を解決した上でざっくりとシステムの関係性を理解することができる資料を作ることをゴールとしました。

ざっくりと書いているのは、細かい処理まで網羅すると巨大なドキュメントになってしまうこと、とっかかりとなる起点さえ抑えておけば必要に応じて掘り下げていくことができると考えたためです。

その名も「解体新書」

シーケンス図、君に決めた

APIやDBという登場人物がいて、処理の順序を可視化するために良く利用されるものがシーケンス図で、UMLの中でわたしが一番良く使っている図です。
今回は、このシーケンス図を利用してプロダクトの主要なユースケースにおけるサービス間の関係性を可視化していきます。

上記の例では、フロントエンドの画面からAPIに対して「スペース一覧の取得」をリクエストし、レスポンスが返却される、というシンプルな処理の流れを表しています。

どうやって作ったのか

1. ユースケースの洗い出し

まずは、プロダクトにおける主要なユースケースを洗い出し、以下の6つに絞りました。

• ユーザー登録
  • スペースマーケットでは、部屋や物件のオーナーをホスト、スペースを利用したい一般ユーザーをゲストと2種類のユーザーが存在します
• ホストの審査
• ホストが所有するスペースの登録
• 登録されたスペースの審査（承認されると検索結果に出るようになる）
• ゲストによるスペースの検索
• スペースの予約

2. ソースコードリーディング

各ユースケースにおいて、どのようなサービスが関わっているかをソースコードを読みながら洗い出していきます。
ただし、処理の詳細までは追わず、呼び出しているAPI単位で「どういう目的で呼ばれているか」「INとOUTがどうなっているか」を把握することにとどめています。
ちなみにソースコードからChatGPTやCopilotを利用してドキュメントを自動作成することもできますが、今回は多数のリポジトリを横断して全体像を掴むことができる抽象度で作成したかったためほぼ手作業で行っています。
（うまいやり方があれば教えてください！）

とはいえどこから着手すれば・・というところですが、まずは画面にアクセスしたときに飛ぶAPIのリクエストから見ていくと追いやすいと思います。
CSRであれば、ブラウザの開発者ツールにあるネットワークタブからどのAPIが呼ばれているかを確認します。
SSRの場合は、対象ページのソースコードから getServerSideProps で呼ばれているAPIを探します。 ^[2]

3. そしてできあがったもの

シーケンス図を作成のツールはMermaid やPlantUMLなどを始めコードで書けるツールがありますが、今回は社内で設計やブレストをする際によく利用されているFigJamを採用しました。

業務の空き時間にちょっとずつ作っていたのと、途中で育休を挟んだため半年ほどかかりましたが何とか完成させることができました。

以下はスペース検索の例です。

ゲストユーザー、複数のAPIサービス、DB、Elasticsearchなどの外部システムから成り立っており、ゲストがスペースマーケットにアクセスをして検索結果を得るまでにどのような順序でどこにアクセスが行くのかといった概要を掴むことが可能になっています。
また、注釈やメモなどは付箋に残していたり、コアドメインと思われる箇所は該当コードのGitHubへリンクを貼るなどしています。

FigJamでの作図は視覚的に操作しやすく、気になった箇所などを付箋で横にメモとして残したりできることが嬉しい反面、途中で何かを差し込んだり消したりすると全体をずらしたり移動したりしないとバランスが悪くなるので非常に大変です。

次は絶対にMermaidにします。

ちなみに全体感はこんな感じ。

まとめ

プロダクトを構成するサービス間の関係性を理解するために、シーケンス図を作成することで新しく入ってきた方のオンボーディングにも役立ちますし、既存メンバーへのさらなる理解促進を行うことができます。

スペースマーケットではテックサロンという、1週間のうち20％を技術力向上や知見共有といった取り組みに当てることができる時間を用意しているのですが、こういった場を利用してバックエンドエンジニア以外への共有を行うなどチーム全体でプロダクトの理解を深める活動にも解体新書を活用することができました。

脚注

1. DBを共有しているサービスが多く、正確にいうと分散モノリスの状態です。この話は別の機会に語ろうと思います。

2. スペースマーケットはNext.jsを利用しています。