AI Des2Code

apps/des2code は V2 design-to-code flow の非同期 matching worker です。 project scope の canonical design を 1 件読み、project の current DocumentDB code_index が ready であることを要求し、implementation と rendered state の evidence を取得し、解決済み code dependency を展開して、production の full-catalog matching workflow を実行します。

worker は source code を生成しません。選択した implementation を matchedCodes、具体的な Figma node/component/state occurrence を usageMatches として返します。各 attempt は request scope の success または failure artifact を S3 に書き、完了を POST /v1/webhooks/ai-status に報告します。

現在の ownership:

Trigger: SQS des2code queue
Canonical read: DocumentDB design, code, code_variation, code_graph, code_index
Primary output: request scope の S3 result artifact と backend webhook
Artifact key: {organization_id}/{project_id}/des2code/{design_id}/{request_id}.json
Backend read: 認可済み design prefix 配下の最新の有効な artifact。 PostgreSQL に Des2Code result row は保存しない
Result の DocumentDB write なし: 5 collection は再利用可能な import/index evidence を保持し、run result は保持しない

技術スタック

Runtime: AWS Lambda 上の Python 3.12
Queue: partial-batch failure reporting を有効にした Amazon SQS
Canonical database: AWS では Amazon DocumentDB 8.0、local development では MongoDB Atlas も対応
Vector retrieval: code semantic/context vector と rendered variation visual vector。すべて 512 次元
Deterministic ranking: packages/des2code-core
Model matching: 必須の MATCHING_MODEL（deployed configuration は openai:gpt-5.6-luna）を使う PydanticAI structured stage
Embedding: EMBEDDING_PROVIDER で OpenAI または OpenRouter を独立選択
Artifact store: Amazon S3
Notification: 認証付き backend AI-status webhook
RDB access なし: worker は PostgreSQL/MySQL を読み書きしない

以前の方向性との差分

項目	以前の方向性	現在の V2
主責務	design から implementation code を生成	import 済み implementation と rendered Storybook state を design occurrence に対応付ける
Project readiness	PostgreSQL codebase-index row/token	scope ごとに 1 件の DocumentDB `code_index`。status は `ready` / `stale`
Retrieval	code の visual + semantic vector	code semantic/context vector、design region、variation visual vector、graph neighbor
Code visual vector	`code` に保存して検索	保存しない。rendered state vector は `code_variation` に保持
Matching model	optional top-candidate reranker	必須の structured planner/family/reranker/occurrence/structural/state-resolution stage
Catalog scope	bounded retrieval candidate のみ	ranking は bounded retrieval、occurrence identity は full scoped catalog
Output	generated source code + code summary	`matchedCodes`, `usageMatches`, bounded diagnostics, matcher config, model summary
Result store	worker 所有 DB/run row	request scope の S3 artifact。backend が最新の有効 artifact を探索
PostgreSQL effect	最新 Des2Code status/result を保存	なし。webhook は design scope を検証し operational log のみ記録

処理フロー

flowchart TD
    A["SQS des2code record"] --> B["design_id, project_id,<br/>organization_id, request_id を検証"]
    B --> C["scope 付き canonical design を読む"]
    C --> D["current code_index status=ready を要求"]
    D --> E["aligned term を memory 上で導出"]
    E --> F["semantic/context vector と<br/>region context で code を取得"]
    F --> G["code_variation から rendered state を取得"]
    G --> H["解決済み code_graph neighbor を展開"]
    H --> I["bounded candidate を deterministic rank"]
    I --> J["full scoped code + variation catalog を読む"]
    J --> K["structured planner/family/reranker/<br/>occurrence/structural/state stage"]
    K --> L["ID を照合し usage を deduplicate、<br/>diagnostics を生成"]
    L --> M["request scope の success artifact を S3 に保存"]
    M --> N["success webhook を POST"]

    B -. validation failure .-> X["scope が安全なら failed artifact を保存"]
    C -. read failure .-> X
    D -. missing or stale .-> X
    K -. processing failure .-> X
    X --> Y["failed webhook を POST"]
    Y --> Z["SQS retry のため re-raise"]

Lambda handler は batchItemFailures を返します。Webhook delivery failure も SQS で retry されます。success artifact が既に書かれている場合、retry は同じ request key を再利用し、別の logical result は作りません。

Hybrid matching 戦略

Des2Code は retrieval、implementation ranking、occurrence identity、 Storybook state resolution を分離します。

Stage	現在の動作	Output
Readiness	current scoped `code_index` 1 件に `status=ready` を要求	Index ID、context vocabulary、variation policy
Aligned terms	design term と current index context の積集合を memory 上で計算	`structure.aligned_terms`。`design` へは保存しない
Screen retrieval	`code.semantics.vector_embedding` と `code.context.vector_embedding` を query	scoped code candidate
Region retrieval	最大 32 design region の embedding で code context を query	region score と matched node ID
State retrieval	screen と region で `code_variation.visual.vector_embedding` を query	parent code ごとの variation evidence
Graph expansion	scope 付きの解決済み `code_graph` edge を traverse	referenced implementation candidate
Deterministic rank	merged bounded pool を `des2code-core` で rank	stable candidate evidence と similarity
Model matching	compact full catalog で plan/family resolve、retrieval rerank、occurrence/structure match、state resolve	検証済み component order と node-level usage
Reconciliation	unknown code/node/variation ID を拒否し、unsupported alternative を抑制して `(nodeId, codeId)` を deduplicate	final `matchedCodes` と `usageMatches`

model には raw storage ID を直接渡しません。temporary alias は scoped catalog に照らして検証してから hydrate します。top vector candidate に入らなかった component でも occurrence matching では full scoped catalog から選択できますが、 retrieval reranking は取得済み candidate に制限されます。

出力形状

process_record() は test と local tool に以下の success payload を返します。 S3 artifact は同じ result を request/index identity、timestamp、matcher configuration、安全な model summary とともに wrap します。

{
  "type": "des2code",
  "recordId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "organizationId": 1,
  "status": "success",
  "result": {
    "matchedCodeCount": 1,
    "matchedCodes": [
      {
        "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
        "name": "Button",
        "semanticValue": ["button", "action", "cta"],
        "similarity": 0.92,
        "visualSimilarity": null,
        "semanticSimilarity": 0.89,
        "contextSimilarity": 0.84,
        "regionSimilarity": 0.91,
        "variationSimilarity": 0.95,
        "variationMode": "state_required",
        "evidenceCategories": ["semantic", "context", "variation"],
        "termOverlap": ["button", "submit"],
        "matchedRegions": ["40002029:37101"],
        "sourceCode": "export default Button;",
        "cssCode": ".button { ... }"
      }
    ],
    "matchedUsageCount": 1,
    "usageMatches": [
      {
        "nodeId": "40002029:37101",
        "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
        "variationId": "visual_primary",
        "variationName": "Primary",
        "confidence": 0.97,
        "evidenceCategories": ["instance/property identity", "visible text"],
        "matchedTerms": ["submit", "primary"]
      }
    ],
    "retrievalDiagnostics": {},
    "usageDiagnostics": {}
  }
}

visualSimilarity は API compatibility のため保持しますが、code に visual vector がないため現在は null です。variationSimilarity は rendered state evidence を表します。codeIndexId は internal result block ではなく S3 artifact に保存されます。