かけあい システム構成

Architecture guide

かけあい システム構成

成果物の読み方、構成上の要点、再生成方法をまとめています。

構成図を見る Markdown原文

このフォルダは、リポジトリの実装・設定から説明できる現状構成を、2枚の主図と5枚の補足図で整理したものです。最初は index.html をブラウザで開くと、7枚の図とブラウザ用に整形した各資料を確認できます。Markdown原文には、各HTMLページ上部のリンクから移動できます。

対象は production用設定に基づく論理構成 です。調査基準は2026-10-01、branch main、commit 30b101f70ea31c11706ea148f7272fbc29053a69。開始時のworktreeはcleanで、実ホスト・Cloudflare・OpenAI・DB等の実稼働には接続していません。DB方式の旧図だけはGit tag v2026.09.29を履歴基準にしています。

読む順序#

  1. 関係者向けサービス全体図 — 30秒で利用者、管理範囲、外部サービス、主な保存先を確認
  2. エンジニア向けシステム構成図 — 実行単位、通信、認証、永続化、blue/green構成を確認
  3. Blue-Green Deployment構成図 — Worker数、空slotの起動、readiness、HAProxy切替、drainを確認
  4. 旧・単一runtime構成図 — combined processの停止・再作成方式を確認
  5. データの流れと保存先 — 認証、業務データ、AI処理、外部ファイルの入力・処理・保存先を確認
  6. 2026-09-29時点の旧DB操作・処理 — 組織全体snapshot、組織共通lock、AI処理前後の全量依存を確認
  7. 現在のDB操作・処理 — 対象別query、entity transaction、row lock/CAS、AI対象文脈を確認
  8. DB操作・処理の新旧比較／データフローの説明／デプロイ方式の比較説明 — 詳細説明を確認
  9. 構成根拠／調査・検証記録 — 根拠、不整合、未確認事項、描画確認
  10. 共通モデル — 図のノード・接続・根拠参照を機械可読で確認

A. 関係者向け#

かけあい 関係者向けサービス全体図

  • 通常の画面・API通信もCloudflare Edge/Tunnelを通ります。Cloudflare Accessによるスタッフ認証は管理画面だけです。
  • 目標・成果物・相談は自社管理PostgreSQL、パスワード等の認証データはCloudflare D1へ分離されます。
  • AI入力は氏名の置換や識別情報の除去後にOpenAIへ送られます。ファイル本体はuploadせず、外部URLだけを保存します。

B. エンジニア向け#

かけあい エンジニア向けシステム構成図

実線は要求・主要データの論理方向で、応答は同じ接続を戻ります。青の破線E05は cloudflared が外向きにTunnel接続を確立する方向、灰色の点線E15は利用者が任意に外部リンクを開く経路です。

production設定では同じNext.js imageをWeb roleとAI Worker roleに分け、HAProxyの背後でblue/green slotとして動かします。WebはPostgreSQLに永続command/jobを投入し、WorkerがclaimしてOpenAIを呼び、結果をPostgreSQLへ反映します。これは設定・実装確認であり、active slotや実配備方式は未確認です。

現在のproduction入力例では、Tunnelから受ける固定HAProxy originは 127.0.0.1:3001、blue slotはWeb :3002／Worker :3012、green slotはWeb :3003／Worker :3013です。

C. Blue-Green Deployment構成#

かけあい Blue-Green Deployment構成図

平常時はactive slotにWeb container 1つとAI Worker container 1つが動きます。更新時だけ空slotに新しいWebとAI Workerを起動するため、一時的にAI Worker containerは新旧2つになります。各worker process内では、AI生成、フィードバック、production command反映の3 processorが動きます。

readiness成功後にHAProxyのweightを切り替えます。旧Webは接続数0まで、旧Workerは旧releaseのbackground job、実行中attempt、command execution、OpenAI provider leaseが全て0になるまで残します。実行中のgeneration／feedbackはdrain modeでabortせず完了を待ち、保持中はrollbackできます。

無停止の対象は、同じmigrationVersionで行う通常リリースです。単一runtimeからの初回移行と非互換DB変更は計画停止を要します。実環境でのSLAや無停止実績を表す図ではありません。

D. 旧・単一runtime構成#

かけあい 旧・単一runtime構成図

旧・代替実装では、Next.js Web/APIとAI Workerが1つのcombined containerで動きます。更新時は既存containerを停止・削除してから新containerを起動し、readiness成功後にTunnelを開始するため、新旧runtimeの同時稼働やdrainはありません。

永続jobはPostgreSQLに残りますが、process停止中のWeb受付とWorker実行は連続しません。この方式の採用履歴と現在の稼働は未確認です。詳細は デプロイ方式の比較説明 を参照してください。

E. データの流れと保存先#

かけあい データの流れと保存先

認証・セッション、画面・業務データ、AI処理、外部ファイルを4つの流れに分け、入力、サーバー側処理、外部連携、永続保存先を示します。同じcomponentをデータ種別ごとに繰り返しており、物理instance数を表す図ではありません。

認証秘密はD1、業務データ・session・AI結果はPostgreSQLへ保存します。AI入力は最小化後にOpenAIへ送信し、外部ファイルはURLだけを保存して、ファイル本体をブラウザが外部保管先から直接取得します。詳細は データフローの説明 を参照してください。

F. 2026-09-29時点の旧DB操作・処理#

2026-09-29時点のDB操作・処理

Git tag v2026.09.29の業務PostgreSQL処理は、組織全体を1つのAppData snapshotとして扱う方式です。readはrevision別cacheを持ちますが、cache missや更新後には組織内41業務表を読みます。writeは組織共通advisory transaction lock内で全量read・cloneし、変更aggregateだけを書いた後、組織revisionを更新して全量再検証します。

永続AI jobとclaim／leaseはすでにありましたが、Workerの入力文脈取得と結果反映は全snapshotに依存していました。同一組織のlock待ちがconnectionを保持し、pool枯渇がread・認証・readinessへ波及したことが、9月30日の調査記録に残っています。

G. 現在のDB操作・処理#

現在のDB操作・処理

現在の主要画面・通常APIは、route、actor、team、artifact等の対象に必要な行だけを複数の限定SQLで取得します。通常writeはentity repositoryの短いtransactionでlive認可し、対象行lockまたはrevision／lease CASを使います。異なるentityは原則として互いを待ちません。

AI WorkerはSKIP LOCKEDとleaseでjobをclaimし、対象workflow graphと直近履歴だけを読みます。OpenAI呼び出し中はDB transactionを保持せず、応答後に対象別transactionで結果を反映します。旧snapshot repositoryは、import・保守・bootstrapと非本番fallbackに限定して残ります。詳しくは DB操作・処理の新旧比較 を参照してください。

重要な注意#

  • プライバシーポリシー v1.6 の「相談内容・成果物の通信はCloudflareを経由しない」という記述と、現在のTunnel設定が一致しません。図は実装・設定に合わせています。
  • プライバシーポリシーの復旧backup保持3か月と、production入力例の30日が一致しません。定常backup jobと実行記録も確認できません。
  • 単一Next.js runtimeのComposeとblue/green Web/Worker構成が併存します。主図はproduction用blue/greenを採用しましたが、実ホストの方式は未確認です。
  • 管理画面は通常のスタッフ再認証とserver-sideのadmin／organization権限検査を使います。旧図にあった管理画面専用の短時間session／追加audienceは現在の実装から削除されています。
  • store:false、データ最小化、providerへの送信経路は実装確認済みです。OpenAI/Cloudflare側の契約、保持、region、学習利用設定は管理画面・契約確認が別途必要です。
  • 通常production APIは対象別DB経路へ移行済みですが、全量snapshot repository自体はimport・保守・bootstrap・非本番fallbackのために残っています。

再生成と検証#

Node.js 22と、このリポジトリに既にあるsharpを使います。ネットワーク、外部レンダリングAPI、CDN、Webフォントは不要です。

node docs/architecture/tools/generate.mjs
node docs/architecture/tools/verify.mjs
  • 共通内容: architecture-model.json
  • 手動調整した配置: sources/layouts.mjs
  • SVG/PNGとMarkdown閲覧HTML生成: tools/generate.mjs、tools/render-markdown.mjs
  • 根拠行・ID・寸法・安全性検査: tools/verify.mjs

SVGは主閲覧用、PNGは資料貼り付け用です。SVGだけを直接修正せず、モデルまたはレイアウトソースを変更して再生成してください。