全体像Architecture
実装した共通土台が、本番環境でどう連動するかを 1 枚にまとめました。話の筋は一本です。1 つのリポジトリ（モノレポ）からビルドし、4 つのサービス + 1 つのジョブとして本番（Cloud Run）へ送り出し、外部サービス（データベース・ストレージ・Drive・メッセージ基盤）へ繋ぐ ── この流れと、作った成果物の全件一覧をこのページに置きます。各テーマの詳細は、以降のページへ展開します。
器から動く土台へFrom repository to runtime
クラウド基盤を「器」とすると、その器に収める「中身（コード）」を実装し、本番で動く状態まで運びました。上から下へ、リポジトリ → ビルド → 本番サービス → 外部接続、と追えるように配置しています。
読み方: 上 3 段（リポジトリ → ビルド → 本番）が主役です。matsuba-web / -api / -sync / -scanner の 4 サービスと、定期処理を 1 つに束ねた matsuba-batch ジョブが、本番にデプロイされ /health（生存確認エンドポイント）に応答するところまで確認しました。最下段の外部サービスのうち、Google Drive への同期など「業務処理そのもの」は、破線で示した今後の実装分です。
実装した成果物の一覧What we built
コードとして実装・整備したものを、テーマ別に並べました。それぞれの設計意図と仕組みは、対応するページに展開しています。件数は実際のコードに合わせています。
| テーマ | 成果物 | 件数 | 役割 |
|---|---|---|---|
| モノレポ | ワークスペースの 4 軸 | 4 軸 | pnpm workspace / Turborepo / go.work / Buf。複数言語・アプリを 1 リポジトリで管理 |
| アプリ | Cloud Run サービス / ジョブ | 4 + 1 | web / api / sync / scanner ＋ ジョブ batch（定期処理の統合） |
| 共通部品 | 共通パッケージ @repo/* | 7 | database / shared / auth / events / ui / eslint 設定 / TypeScript 設定 |
| 型と契約 | イベント定義（protobuf） | 13 | 4 つの定義ファイルから TypeScript と Go を自動生成 |
| データベース | 限定値の型（Prisma Enum） | 10 | 状態・種別・ロール等、決まった値だけを取る列を型で固定 |
| データベース | 認可判定ヘルパ（RLS 関数） | 8 | 「誰がどの Box の何を見てよいか」を DB 側で判定する関数 |
| データベース | マイグレーション | 6 | スキーマ（テーブル設計）の変更履歴 |
| イベント基盤 | ワーカー（worker） | 18 | 送り出し役 outbox-dispatcher を実装、残り 17 は今後実装する処理の枠（スタブ） |
| イベント基盤 | Pub/Sub の受け渡し基盤 | 13 + 13 / 22 | 主トピック + 退避先（DLQ）+ サブスクリプション（前段で整備済の流通路に接続） |
| 画面基盤 | 画面部品（shadcn/ui）の精査 | 55 | 1 つずつ採否を判断（採用 19 / 個別修正 35 / 不採用 1） |
| 自動デプロイ | CD ワークフロー | 5 | サービス別 4 本 + 共通の再利用ワークフロー 1 本（キーレス） |
「土台」であることの意味: 上記はいずれも、業務機能（ファイル共有や通知の中身）そのものではなく、それらを安全・確実に載せるための骨格です。骨格を先に正しく組んでおくことで、後から機能を追加するたびに発生しがちな手戻り・不具合・抜け漏れを構造的に減らせます。
到達点Where we are
誇張せず、事実として「どこまで動く状態になったか」を記します。「疎通（そつう）」とは、リクエストや通知が経路を通って相手に届き、応答が返る状態を指します（平たく言えば「ちゃんと繋がって動く」状態）。
手元のパソコンで 4 サービスを起動し、本番のデータベース等に繋いで /health が応答。
自動デプロイで本番（Cloud Run）へ送り出し、*.run.app の /health が 200 応答。
1 つの定義から TypeScript・Go の型を生成。送り手と受け手の型ズレを構造的に排除。
ファイル操作・通知などの中身は、この土台の上に今後 載せていきます。
正直な注記: 現時点では各サービスは「起動雛形（中身が空の骨格）」の段階で、ファイル一覧や共有リンクといった業務処理はこれから実装します。本資料の図では、こうした今後の実装分を破線、実装して本番疎通まで確認したものを実線で示し、区別できるようにしています。