WF2Des Table

Overview

Client-facing status row for one generation run on either edge — wireframe-to-design or design-to-wireframe, discriminated by edge: one row per generation request, created by the backend wf2des-api and returned by the POST (201) and polled by GET. It is the sole PostgreSQL surface for both edges' generation runs — the backend owns every write (row creation plus the ai-status webhook / confirm / placement / feedback endpoints); workers NEVER write it.

Table Definition

Logical Name	Physical Name	Column Name	Data Type	Primary Key	Relation	Unique	Nullable	Default Value	Remarks
WF2Des	wf2des	id	string	◯					uuid (varchar(255)). Client-facing request id — the POST 201 target and the GET poll key; echoed to the worker/webhook as job_id. The client-facing status row, updated only backend-side
		organization_id	number		organization:id				tenancy scope; DEFAULT_ORGANIZATION_ID=1 today
		project_id	number		project:id				tenancy scope. Part of the secondary discovery index (organization_id, project_id, figma_file_key, status) — deferred-materialization discovery
		figma_file_key	string						target Figma file. Part of the partial-unique (figma_file_key, wf_node_id) WHERE status = '0' — one live generation per WF node (a duplicate trigger → 409 + the existing id)
		wf_node_id	string						target WF frame node id (the second half of the open-generation dedupe key)
		screen_id	string						screen ID, prefilled from the frame name and user-confirmed
		prompt	string				◯		optional generation prompt (selection input, ranked below memo intent)
		placement_target	string				◯		optional placement node id, echoed into the result doc request block
		auto_confirm	enum					'0'	wf2des_auto_confirm — '0' normal (parse-confirm step) / '1' auto-confirm (parse + assemble in one invocation)
		trigger_surface	enum						wf2des_trigger_surface — '0' api / '1' plugin (derived backend-side from the authenticated surface)
		status	enum					'0'	wf2des_status (see Type Codes)
		phase	enum				◯		wf2des_phase — generation orchestration inside status '0' (see Type Codes). NULL once terminal. Surfaced on GET / list
		attempt	number					1	monotonic fencing counter — fixed at 1 today; no endpoint bumps it (there is no requeue path); DocumentDB result-doc writes and webhook effects compare it (CAS on (_id, attempt))
		error_message	string				◯		client-visible failure detail, recorded from the failed webhook manifest (text)
		result_url	string				◯		terminal result / failed artifact S3 key
		flag_count	number				◯		completion-time copy of the result doc's confidence.flag_count — surfaces on GET / list so consumers see flags without a data-plane call
		materialized_at	datetime				◯		set via the backend placement endpoint after the plugin builds the frame
		feedback_status	enum				◯		wf2des_feedback_status — '0' fixed / '1' adopted (recorded by the backend feedback endpoint; bookkeeping only)
		created_at	datetime
		updated_at	datetime
		deleted_at	datetime				◯		soft delete
		created_by	string		user:cognito_sub				system writes (webhook / enqueue) use the service-account cognito_sub
		updated_by	string		user:cognito_sub
		deleted_by	string		user:cognito_sub		◯
		edge	enum					'0'	wf2des_edge — which edge produced the row: '0' wf2des / '1' des2wf. Part of the open-generation partial-unique key, so an in-flight run on one edge never blocks the other
		score	number				◯		completion-time copy of the run's score (numeric(5,4)) — surfaces on GET / list so consumers see it without a data-plane call. NULL where the completion effect reports no score
		score_version	string				◯		varchar(32) — the score formula version the run was scored under (ds@1.0 on the des2wf edge). Scores are never compared across versions; the field is traceability

Relations

• organization_id → organization.id
• project_id → project.id
• Audit fields (created_by / updated_by / deleted_by) reference user.cognito_sub; system-side writes use the service-account cognito_sub
• (figma_file_key, wf_node_id) identifies the target WF frame; the assembled result lands in the shared platform design registry (type=component context) via the completion flow, not through a foreign key here
• 1:1 with the design_generation_result DocumentDB document, whose _id equals this id

Indexes

• PRIMARY KEY (id)
• PARTIAL UNIQUE INDEX wf2des_open_generation_uq (project_id, figma_file_key, wf_node_id, edge) WHERE status = '0' — one live (in-progress) generation per WF node per project, per edge; a duplicate trigger returns 409 with the existing run id. A run left non-terminal keeps blocking new triggers for that wireframe until it reaches a terminal status plus the existing id
• INDEX wf2des_org_project_file_status_idx (organization_id, project_id, figma_file_key, status) — deferred-materialization discovery / list queries
• UNIQUE handling on deleted_by / deleted_at follows the standard soft-delete audit pattern

Type Codes

status (wf2des_status) — generation only; internal wf2des worker runs carry no row:

Value	Meaning
'0'	processing
'1'	completed
'2'	failed
'3'	rejected (designer declined the parse; NOT failed)
'4'	cancelled (set by the cancel endpoint)

phase (wf2des_phase) — namespaced INSIDE status '0', independent of the status codes; cleared (NULL) once the row reaches a terminal status:

Value	Meaning
'0'	parse
'1'	awaiting_confirm
'2'	assemble

auto_confirm (wf2des_auto_confirm): '0' normal (parse-confirm step) · '1' auto-confirm (parse + assemble in one invocation).

trigger_surface (wf2des_trigger_surface): '0' api · '1' plugin (derived backend-side from the authenticated surface).

feedback_status (wf2des_feedback_status): '0' fixed · '1' adopted (recorded by the backend feedback endpoint; bookkeeping only).

edge (wf2des_edge): '0' wf2des · '1' des2wf — which edge produced the row; part of the open-generation partial-unique key.

Notes

• Backend-owned: the wf2des worker holds no PostgreSQL credentials and NEVER writes this table. Every PG effect is applied backend-side — the ai-status webhook handler is the sole completion-time writer (flips status/phase, records result_url/error_message/flag_count, attempt-guarded in one transaction), while the confirm / placement / feedback endpoints handle the interactive transitions.
• Row-first-then-SQS: the backend INSERTs the row (status '0', phase '0' parse) before enqueuing the generation message, so the client always has a poll target.
• The confirm endpoint CAS-matches phase '1' awaiting_confirm + attempt before advancing to phase '2' assemble; a parse reject is written by the plugin (parse.rejected) and the confirm endpoint flips status '3' — it is not a webhook path.
• attempt is the fencing counter shared with the DocumentDB design_generation_result doc (CAS on (_id, attempt)); a superseded attempt's webhook is a no-op.
• flag_count and result_url mirror the terminal design_generation_result document at completion so consumers avoid a data-plane read.
• Enums are stored as numeric-string values ('0', '1', …) matching the platform convention used by design / wireframe.