Skip to content

AI Des2Code

apps/des2code is the asynchronous matching worker for the V2 design-to-code flow. It reads one project-scoped canonical design, requires the project's current DocumentDB code_index to be ready, retrieves implementation and rendered-state evidence, expands resolved code dependencies, and runs the production full-catalog matching workflow.

The worker does not generate source code. It returns selected implementations in matchedCodes and concrete Figma-node/component/state occurrences in usageMatches. Each attempt writes a request-scoped success or failure artifact to S3 and reports completion to POST /v1/webhooks/ai-status.

Current ownership:

  • Trigger: SQS des2code queue
  • Canonical reads: DocumentDB design, code, code_variation, code_graph, and code_index
  • Primary output: request-scoped S3 result artifact plus backend webhook
  • Artifact key: {organization_id}/{project_id}/des2code/{design_id}/{request_id}.json
  • Backend reads: the latest valid artifact under the authorized design prefix; no Des2Code result row is stored in PostgreSQL
  • No result DocumentDB write: the five collections contain reusable import and index evidence, not run results

Tech Stack

  • Runtime: Python 3.12 on AWS Lambda
  • Queue: Amazon SQS with partial-batch failure reporting
  • Canonical database: Amazon DocumentDB 8.0 in AWS; MongoDB Atlas is supported for local development
  • Vector retrieval: semantic/context code vectors and rendered variation visual vectors, all 512 dimensions
  • Deterministic ranking: packages/des2code-core
  • Model matching: PydanticAI structured stages using the required MATCHING_MODEL (openai:gpt-5.6-luna in the deployed configuration)
  • Embeddings: OpenAI or OpenRouter selected independently by EMBEDDING_PROVIDER
  • Artifact store: Amazon S3
  • Notification: authenticated backend AI-status webhook
  • No RDB access: the worker never reads or writes PostgreSQL/MySQL

Differences From The Previous Direction

Area Previous Direction Current V2 Direction
Main responsibility Generate implementation code from a design Match imported implementations and rendered Storybook states to design occurrences
Project readiness PostgreSQL codebase-index row/token One scoped DocumentDB code_index with ready / stale status
Retrieval Visual + semantic code vectors Code semantic/context vectors, design regions, variation visual vectors, and graph neighbors
Code visual vector Stored and searched on code Not stored; rendered state vectors live in code_variation
Matching model Optional top-candidate reranker Required structured planner, family, reranker, occurrence, structural, and state-resolution stages
Catalog scope Bounded retrieval candidates only Bounded retrieval for ranking plus the full scoped catalog for occurrence identity resolution
Output Generated source code + code summary matchedCodes, usageMatches, bounded diagnostics, matcher config, and model summary
Result store Worker-owned DB/run row Request-scoped S3 artifacts; backend discovers the latest valid artifact
PostgreSQL effect Persist latest Des2Code status/result None; webhook validates design scope and records operational logs only

Processing Flow

flowchart TD
    A["SQS des2code record"] --> B["Validate design_id, project_id,<br/>organization_id, request_id"]
    B --> C["Read scoped canonical design"]
    C --> D["Require current code_index status=ready"]
    D --> E["Derive aligned terms in memory"]
    E --> F["Retrieve code by semantic/context vectors<br/>and regions by context vectors"]
    F --> G["Retrieve rendered states from code_variation"]
    G --> H["Expand resolved code_graph neighbors"]
    H --> I["Deterministic rank bounded candidates"]
    I --> J["Load full scoped code + variation catalog"]
    J --> K["Structured planner/family/reranker/<br/>occurrence/structural/state stages"]
    K --> L["Reconcile IDs, deduplicate usages,<br/>build diagnostics"]
    L --> M["Write request-scoped success artifact to S3"]
    M --> N["POST success webhook"]

    B -. validation failure .-> X["Write failed artifact when scope is safe"]
    C -. read failure .-> X
    D -. missing or stale .-> X
    K -. processing failure .-> X
    X --> Y["POST failed webhook"]
    Y --> Z["Re-raise for SQS retry"]

The Lambda handler returns batchItemFailures. A webhook delivery failure is also retried through SQS. If the success artifact was already written, the retry reuses the same request key and does not create a second logical result.

Hybrid Matching Strategy

Des2Code separates retrieval, implementation ranking, occurrence identity, and Storybook-state resolution:

Stage Current behavior Output
Readiness Require one current scoped code_index with status=ready Index ID, context vocabulary, variation policy
Aligned terms Intersect design terms with current index context in memory structure.aligned_terms; never persisted back to design
Screen retrieval Query code.semantics.vector_embedding and code.context.vector_embedding Scoped code candidates
Region retrieval Query code context for at most 32 design regions Region scores and matched node IDs
State retrieval Query code_variation.visual.vector_embedding for the screen and regions Variation evidence grouped by parent code
Graph expansion Traverse scoped resolved code_graph edges Referenced implementation candidates
Deterministic rank Rank the bounded merged pool with des2code-core Stable candidate evidence and similarity
Model matching Plan from compact full catalog, resolve families, rerank retrieval, match occurrences/structures, resolve states Validated component order and node-level usages
Reconciliation Reject unknown code/node/variation IDs, suppress unsupported alternatives, deduplicate (nodeId, codeId) Final matchedCodes and usageMatches

The model never receives raw storage IDs directly. Temporary aliases are validated against the scoped catalog before hydration. A component can be selected from the full scoped catalog for occurrence matching even when it did not appear in the top vector candidates; retrieval reranking itself remains restricted to retrieved candidates.

Output Shape

process_record() returns the success payload below to tests and local tools. The persisted S3 artifact wraps the same result with request/index identity, timestamps, matcher configuration, and a safe model summary.

{
  "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 is retained for API compatibility but is currently null because code has no visual vector. variationSimilarity represents rendered state evidence. codeIndexId is stored on the S3 artifact rather than inside the internal result block.