AI Des2Code - Matching Architecture

This document defines the current matching architecture shared by code import, variation import, design import, code-index rebuild, and Des2Code. Storage is strict and current-state only; matching converts canonical storage to the established runtime shape through validated adapters.

End-to-End Flow

flowchart LR
  backend[guinness-backend] -->|code-import| ci[SQS code-import]
  backend -->|code-variation-import| vi[SQS code-variation-import]
  backend -->|design-import| di[SQS design-import]
  backend -->|code-index| ii[SQS code-index]
  backend -->|design_id + scope + request_id| dq[SQS des2code]

  ci --> code[(DocumentDB code)]
  vi --> variation[(DocumentDB code_variation)]
  di --> design[(DocumentDB design)]
  code --> ii
  variation --> ii
  ii --> graph[(DocumentDB code_graph)]
  ii --> index[(DocumentDB code_index)]

  design --> d2c[AI Des2Code]
  code --> d2c
  variation --> d2c
  graph --> d2c
  index --> d2c
  d2c --> s3out[(S3 request artifact)]
  d2c --> webhook[Backend webhook]

PostgreSQL remains the product identity/authorization source used by the backend. The AI worker never receives PostgreSQL credentials and never stores a Des2Code run in DocumentDB.

Design Import Contract

Design Import writes one current strict design document for a Figma design. It does not require or pin a code index.

Input identity:

Field	Purpose
`design_id`	Stable canonical `_id`
`organization_id`, `project_id`	Tenant/project scope
`file_id`, `node_id`	Figma provenance
`img_url`	Rendered screen image
`json_schema_url`	Figma JSON object read and validated by the worker

Persisted matching evidence:

Block	Contents
`visual.metadata`	name, image URL, layout, component types, palette, typography; no vector
`semantics.metadata.words`	generated intent vocabulary
`semantics.vector_embedding`	512-dimensional semantic vector
`structure.metadata`	visible text, generic terms, bounded regions, concrete component instances
`structure.vector_embedding`	512-dimensional screen structure vector
`structure.metadata.regions[].vector_embedding`	512-dimensional regional structure vectors
`processing.hash`	SHA-256 idempotency fingerprint

Design Import preserves Figma component/component-set identity, instance properties, bounds, hierarchy, path, visible text, and summaries. It does not persist project-aligned terms. Des2Code derives those terms against the current code_index.context.terms at request time.

Code Import Contract

Code matching evidence is split by responsibility:

Collection	Writer	Current content
`code`	`code-import`	source/CSS, semantic vocabulary/vector, parsed source-context/vector, non-vector visual metadata
`code_variation`	`code-variation-import`	one successfully rendered Storybook state, image metadata/description, visual vector
`code_graph`	`code-index`	current resolved code reference edges
`code_index`	`code-index`	one current scoped readiness document, context terms, and per-code variation mode

Effective code or code_variation changes mark the current code_index stale. The explicit rebuild obtains an expiring single-flight lease, validates all code and variation inputs, rebuilds resolved graph edges, and publishes the ready index transactionally.

code intentionally has no visual vector or embedded variation inventory. Only successfully rendered states are stored in code_variation; declarations without a render do not participate in state matching.

Matching Pipeline

Stage	Behavior
1. Scope/readiness	Read design and index by exact organization/project scope; require strict schema and `code_index.status=ready`.
2. Request alignment	Intersect design terms with current index vocabulary in memory; do not mutate the design.
3. Vector retrieval	Query code semantic/context vectors for the screen, code context for up to 32 regions, and variation visual vectors for the screen/regions.
4. Candidate merge	Merge by code ID and retain maximum semantic/context/region/variation evidence.
5. Graph expansion	Hydrate scoped neighbors from resolved `code_graph` edges.
6. Deterministic ranking	Rank the bounded merged pool with `des2code-core` and current variation policy.
7. Full-catalog planning	Present compact aliased catalog identity to the structured planner and family resolvers.
8. Retrieval reranking	Reorder retrieved candidates only; unknown and non-retrieved IDs cannot enter this order.
9. Occurrence matching	Match concrete valid Figma node IDs to detailed aliased code candidates using image, properties, text, structure, and source evidence.
10. Structural ownership	Resolve layout/structural owners and preserve supported parent/child dependencies.
11. State resolution	Map state-required occurrences to known scoped `code_variation` IDs; reconcile specific stories from properties.
12. Final guards	Add strict deterministic matches, remove nested duplicates/unsubmittable matches, canonicalize anchors, suppress unsupported competitors, and deduplicate `(nodeId, codeId)`.
13. Artifact/webhook	Persist the complete request artifact and notify backend.

The model-facing prompt payload is bounded to 700,000 UTF-8 bytes. Typed stage outputs limit candidate, node, and decision counts. Every storage identity is represented by a temporary alias and mapped back only after validation.

Match Output Evidence

Implementation-level output:

Field	Meaning
`similarity`	Deterministic rank score for the implementation candidate
`visualSimilarity`	Compatibility field; currently `null` because `code` has no visual vector
`semanticSimilarity`	Code semantic retrieval score
`contextSimilarity`	Screen-to-code context score
`regionSimilarity`	Best region-to-code context score
`variationSimilarity`	Best rendered-state visual score for the parent code
`variationMode`	`identity_only` or `state_required` from current index profile
`evidenceCategories`, `termOverlap`, `matchedRegions`	Bounded explainability evidence

Occurrence-level output:

Field	Meaning
`nodeId`, `codeId`	Concrete Figma occurrence and selected implementation
`variationId`, `variationName`	Resolved rendered state, or `null` when absent/not required
`confidence`	Validated `0..1` occurrence confidence
`evidenceCategories`, `matchedTerms`	Bounded occurrence/state evidence

The artifact also stores retrieval/usage diagnostics, current codeIndexId, effective matching bounds, and a secret-free provider/model/prompt summary.

Compatibility Rules

Storage contracts reject undeclared legacy fields and invalid vector lengths.
Canonical persisted vectors always contain exactly 512 finite values.
Runtime adapters preserve established matcher keys without weakening storage.
codeIndexId identifies the current scoped singleton used by the run; it is not a historical version or PostgreSQL token.
Design import is independent of index readiness; a later code-index rebuild does not require design reimport.
Des2Code fails closed on missing/stale index, scope mismatch, malformed catalog identity, unknown model IDs, or invalid state identity.
Model/provider selection is environment-owned. No request-level fallback or override is accepted.
Matching remains project-agnostic: behavior comes from imported evidence and the current catalog/profile, not hardcoded project-specific expected results.