# かけあい システム構成

このフォルダは、リポジトリの実装・設定から説明できる現状構成を、2枚の主図と5枚の補足図で整理したものです。最初は [index.html](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. [関係者向けサービス全体図](01-stakeholder.svg) — 30秒で利用者、管理範囲、外部サービス、主な保存先を確認
2. [エンジニア向けシステム構成図](02-engineer.svg) — 実行単位、通信、認証、永続化、blue/green構成を確認
3. [Blue-Green Deployment構成図](supplementary/03-blue-green-deployment.svg) — Worker数、空slotの起動、readiness、HAProxy切替、drainを確認
4. [旧・単一runtime構成図](supplementary/04-legacy-single-runtime.svg) — combined processの停止・再作成方式を確認
5. [データの流れと保存先](supplementary/05-data-flow.svg) — 認証、業務データ、AI処理、外部ファイルの入力・処理・保存先を確認
6. [2026-09-29時点の旧DB操作・処理](supplementary/06-database-operation-legacy.svg) — 組織全体snapshot、組織共通lock、AI処理前後の全量依存を確認
7. [現在のDB操作・処理](supplementary/07-database-operation-current.svg) — 対象別query、entity transaction、row lock/CAS、AI対象文脈を確認
8. [DB操作・処理の新旧比較](supplementary/database-operation-comparison.md)／[データフローの説明](supplementary/data-flow.md)／[デプロイ方式の比較説明](supplementary/runtime-comparison.md) — 詳細説明を確認
9. [構成根拠](evidence.md)／[調査・検証記録](verification.md) — 根拠、不整合、未確認事項、描画確認
10. [共通モデル](architecture-model.json) — 図のノード・接続・根拠参照を機械可読で確認

## A. 関係者向け

[![かけあい 関係者向けサービス全体図](01-stakeholder.png)](01-stakeholder.svg)

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

## B. エンジニア向け

[![かけあい エンジニア向けシステム構成図](02-engineer.png)](02-engineer.svg)

実線は要求・主要データの論理方向で、応答は同じ接続を戻ります。青の破線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構成図](supplementary/03-blue-green-deployment.png)](supplementary/03-blue-green-deployment.svg)

平常時は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構成図](supplementary/04-legacy-single-runtime.png)](supplementary/04-legacy-single-runtime.svg)

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

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

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

[![かけあい データの流れと保存先](supplementary/05-data-flow.png)](supplementary/05-data-flow.svg)

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

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

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

[![2026-09-29時点のDB操作・処理](supplementary/06-database-operation-legacy.png)](supplementary/06-database-operation-legacy.svg)

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操作・処理](supplementary/07-database-operation-current.png)](supplementary/07-database-operation-current.svg)

現在の主要画面・通常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操作・処理の新旧比較](supplementary/database-operation-comparison.md) を参照してください。

## 重要な注意

- プライバシーポリシー 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フォントは不要です。

```bash
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だけを直接修正せず、モデルまたはレイアウトソースを変更して再生成してください。