AI Internal API — 概要
internal-api アプリは guinness-ai-v2 における VPC 内部 HTTP サービスで、VPC 内部の呼び出し元に DocumentDB + S3 のみ への制御された入口を与えます — PostgreSQL には決して触れず、SQS にも決して触れません。これはスタンドアロンの MCP リード API（mcp-api）を発展的に継承したものであり、1 つの Lambda Function URL の下に 2 つのルートグループ をホストします:
- MCP リード API（
design/code用）— MCP Server が消費する内部リードサーフェス。これは MCP リード API 概要 で別途ドキュメント化されています。このページは それをクロスリファレンスするだけで、再ドキュメント化はしません。 wf2des-apiデータプレーン — wf2des 向けの Figma プラグインのリード/ライトサーフェス。この概要はwf2des-apiグループを中心に扱います。
このアプリが存在するのは、Figma プラグインが wf2des DocumentDB コレクションと S3 アーティファクトへのファーストクラスなアクセスを必要とするためです — parse をプレビューし、spec をマテリアライズし、placement/feedback を書き戻すために — ただし PostgreSQL には触れてはなりません。バックエンドが wf2des PostgreSQL 行と、その上のあらゆる製品向けフラグを管轄します。そのため、プラグインの DocDB/S3 トラフィックはここ（AI 側自身のデータストア）に着地し、あらゆる PG 効果はバックエンド側で適用されます。wf2des-api は データプレーン であり、バックエンドの create / confirm / cancel / placement / feedback エンドポイントが コントロールプレーン です。両者は決して重なりません — このアプリは PG 認証情報を保持しません。
キュー: なし — HTTP のみ（Lambda Function URL。SQS なし、EventBridge なし）
認証: Figma プラグイン向けのプラグイン セッショントークン {org_id, project_id, exp}（read + write、プロジェクトスコープ）。バックエンド / MCP 向けの共有 X-AI-Service-Token（read）
ストア: 6 つの wf2des DocumentDB コレクション + S3 — PostgreSQL には決して触れず、SQS にも決して触れない
ソース: guinness-ai-v2/apps/internal-api/（発展した mcp-api。新規アプリではなく再利用）
技術スタック
| レイヤ | 採用技術 |
|---|---|
| ランタイム | Python 3.12 on AWS Lambda |
| AI フレームワーク | なし — 純粋なデータプレーンのリード/ライト、LLM 呼び出しなし |
| データベース | Amazon DocumentDB（guinness_v2）— 6 つの wf2des コレクション（加えて MCP ルートグループ用の design / code） |
| オブジェクトストレージ | Amazon S3 — spec アーティファクト、parse.json（presign またはプロキシ） |
| キュー | なし — HTTP のみ |
| 認証 | プラグイン セッショントークン {org_id, project_id, exp}（read + write）または 共有 X-AI-Service-Token ヘッダー（read）。いずれも org / project でスコープ |
| デプロイ | Lambda Function URL、VPC 内部のみ。セキュリティグループは VPC 内部の呼び出し元からのインバウンドのみ許可 |
| RDB | アクセスなし — PostgreSQL には決して書き込まず読み込まない。データベース分離を遵守（バックエンドが Postgres を管轄、AI が DocumentDB を管轄） |
| SQS | アクセスなし — このアプリは決してエンキューしない。ジョブトリガーはバックエンド / ワーカー経路に留まる |
このアプリが存在する理由
Figma プラグインは AI 側のクライアントであって、PostgreSQL のクライアントではありません。キャンバス上で仕事をするために wf2des DocDB ドキュメントと S3 アーティファクトを必要とし、いくつかのサブドキュメント（却下理由、placement レポート、feedback）を書き戻す必要があります。しかし wf2des PostgreSQL 行はバックエンド管轄 です — status、phase、materialized_at、feedback_status、そしてあらゆる製品フラグは、バックエンドが反転するものです。プラグインに PG を直接書き込ませることは、その管轄境界を壊すことになります。
wf2des-api はこれをきれいに解決します: プラグインはこのアプリを通じて detail サブドキュメント を DocumentDB に書き込み、その後 バックエンドのフラグエンドポイント を呼び出して行を反転します。AI 管轄のデータは AI 管轄のストアに存在し、バックエンドが唯一の PG ライターであり続けます。これは MCP リード API と同じ分離スタンス — バックエンドが Postgres を管轄、AI が DocumentDB を管轄 — を、リードオンリーから制御されたリード/ライトのデータプレーンへ拡張したものです。
認証モデル
2 つの認証経路があり、いずれも org / project でスコープされ、同じルートを共有します:
| 呼び出し元 | 認証情報 | スコープ | アクセス |
|---|---|---|---|
| Figma プラグイン | セッショントークン {org_id, project_id, exp} |
プロジェクトスコープ、期限あり | read + write |
| バックエンド / MCP | 共有 X-AI-Service-Token ヘッダー |
サービス間 | read |
プラグインのセッショントークンは {org_id, project_id, exp} を運び、書き込みできる 唯一の 認証情報です — しかも自身のプロジェクト内のみです。バックエンドと MCP は read アクセスのために共有 X-AI-Service-Token を使います（MCP リード API の X-AI-Service-Token と同じサービストークンの形状）。あらゆるルートは org / project でスコープされます: トークンは自身のテナントのドキュメントとアセットのみを見て触れます。
Detail-First パターン
書き込みは 1 つの厳格な順序に従います: detail が先、flag が後。
- プラグインは detail サブドキュメント を
wf2des-apiに書き込みます（design_generation_resultドキュメントへの DocumentDB 書き込み — reject / placement / feedback サブブロック）。 - その後にのみ、プラグインは対応する バックエンドのフラグエンドポイント を呼び出し、
wf2desPostgreSQL 行（status /materialized_at/feedback_status）を反転します。
不変条件: wf2des-api は それ自身は決して PostgreSQL に書き込みません。detail は常にバックエンドのフラグが反転する前に DocumentDB に着地するため、PG フラグがその裏付けとなる detail が存在しないまま設定されることは決してありません。フラグ呼び出しが失敗またはリトライされても、detail はすでに永続的かつ冪等です。2 ステップ形状の唯一の例外は ファイル登録（POST/PUT .../figma-files）で、これは wf2des-api への 直接 書き込みです — project_figma_file は DocumentDB コレクションであって PG フラグサーフェスではないため、バックエンドのフラグステップはそもそも存在しません。
ルートサマリー
wf2des-api ルートグループ — VPC 内部 HTTP、DocumentDB + S3 のみ、全ルートが org / project スコープ。リードはプラグインセッショントークン および X-AI-Service-Token に開かれ、ライトはプラグインセッショントークンを必要とします。
| # | Method + Path | 種別 | 何をするか | バックエンドのフラグステップ |
|---|---|---|---|---|
| 1 | GET /internal/wf2des/{wf2des_id}/result |
read | design_generation_result の DesignSpec（spec ブロック。artifact_urls.spec 経由で S3 にスピルしている場合は presign / 返却）を返す。プラグインはこれからネイティブ Figma をマテリアライズする |
— |
| 2 | GET /internal/wf2des/{wf2des_id}/parse |
read | 結果ドキュメントの parse ブロック + イミュータブルな parse.json アーティファクトを、awaiting_confirm の プレビュー（roles / intent / memo_influences）向けに返す。プラグインはこれからプレビューする |
— |
| 3 | GET /internal/projects/{project_id}/figma-files |
read | project_figma_file からプロジェクトの登録済み Figma ファイルをリスト（role working | library、config_url、components_synced_at）。プラグインの org / project + ファイル解決 |
— |
| 4 | POST /internal/wf2des/{wf2des_id}/reject |
write | 結果ドキュメントの parse.rejected = {reason_code, note} を書き込む（reason_code: wrong_roles | wrong_memos | wrong_sections | other） |
→ バックエンドの confirm エンドポイントが行を status '3' rejected に反転 |
| 5 | POST /internal/wf2des/{wf2des_id}/placement |
write | 結果ドキュメントの placement = {placed_node_id, materialized_at, revision, spec_hash, review_id, materializer_report:[{layer_path, event, detail}]} を書き込む（event: name_fallback | ordinal_fallback | build_error | font_fallback | prop_rejected | unmatched | preserved） |
→ バックエンドの placement エンドポイントが行の materialized_at を反転 |
| 6 | POST /internal/wf2des/{wf2des_id}/feedback |
write | 結果ドキュメントの feedback = {status, changed_nodes:[layer_path], diff_url, at, by} を書き込む（status: fixed | adopted） |
→ バックエンドの feedback エンドポイントが行の feedback_status を反転 |
| 7 | POST/PUT /internal/projects/{project_id}/figma-files |
write | project_figma_file（role、config_url）を登録 / 更新。UNIQUE(organization_id, project_id, figma_file_key)。wf2des-api への 直接 書き込み |
— （PG フラグサーフェスなし） |
ルート 1〜3 はリードサーフェス。4〜6 は detail-first の書き込み（各々がバックエンドのフラグエンドポイントとペアになる。detail が先、flag が後）。7 は唯一の直接書き込みです。
ストア
wf2des-api は 6 つの wf2des DocumentDB コレクション と S3 に対して構成されます — それ以外には触れません。wf2des PostgreSQL 行（バックエンド管轄）を 決して 読み書きせず、SQS へ 決して エンキューしません。
| ストア | wf2des-api の使い方 |
|---|---|
DocumentDB design_generation_result |
parse / spec ブロックを読む（ルート 1〜2）。parse.rejected / placement / feedback detail サブドキュメントを書く（ルート 4〜6） |
DocumentDB project_figma_file |
プロジェクトの登録済みファイルを読む（ルート 3）。ファイルを直接登録 / 更新する（ルート 7） |
DocumentDB wireframe |
プレビュー用の parse コンテキストの裏付け（ルート 2） |
DocumentDB design_rule |
parse / spec リードと並んで提示されるルールコンテキスト |
DocumentDB design_component |
spec リードと並んで提示されるコンポーネントインスタンス化コンテキスト（ルート 1） |
DocumentDB design_resolution |
worker-owned section-resolution ledger。shared wf2des data model の一部だが plugin route から直接公開しない |
| S3 | spec アーティファクト（artifact_urls.spec）、イミュータブルな parse.json を presign / 返却 |
MCP リードルートグループは加えて design / code コレクションに触れます。それらは MCP リード API 概要 に属し、ここでは再ドキュメント化しません。
正式なフィールドレベル契約: I/O 定義。