Project Figma File Collection

Overview

Collection for project ↔ Figma-file bookkeeping (moved off PostgreSQL — AI-owned). The plugin file-registration writes role/config_url via wf2des-api; component_sweep writes the sync fields (components_synced_at / sweep_error), captures style_captures, and holds the single-flight sweep_marker. The assemble phase reads style_captures (source of the derived spec style_bindings) and config_url (the DESIGN-area rect).

Table Definition

Logical Name	Physical Name	Column Name	Data Type	Primary Key	Relation	Unique	Nullable	Default Value	Remarks
Project Figma File	project_figma_file	_id	string	◯					uuid stored in DocumentDB _id. Project ↔ Figma file bookkeeping (moved off PG — AI-owned)
		organization_id	number		organization:id				Tenant owner. Part of UNIQUE (organization_id, project_id, figma_file_key)
		project_id	number		project:id				Project scope. Part of UNIQUE (organization_id, project_id, figma_file_key)
		figma_file_key	string						Figma file key (verbatim; alphanumeric, no underscore). Part of UNIQUE (organization_id, project_id, figma_file_key)
		role	number						File role — plugin file-registration writes this via wf2des-api. 0: working (generation output file) 1: library (component/rule source)
		components_synced_at	datetime						Last successful component_sweep — the freshness watermark, updated LAST after the sweep completes
		config_url	string						S3 key of the per-project ingest config.json (WF/DESIGN area patterns, memo markers). Home {org}/{proj}/wf2des/config.json; the assemble phase resolves the DESIGN-area rect from it
		sweep_error	string			◯			Latest component_sweep failure, else null
		style_captures	object						{ <token>: string } — file-level local text styles + color variables, one per figma_file_key; each token maps to a Figma style/variable id. The derived spec style_bindings map is produced from this
		sweep_marker	object			◯			{ token: string, acquired_at: datetime, expires_at: datetime } — single-flight lock for component_sweep (crash-safe with stale-lock recovery; a lock past expires_at is reclaimable). NULL when no sweep is in flight
		index_schema_version	number						Document schema version (schema-governance parity)
		created_at	datetime						Creation timestamp
		updated_at	datetime						Last-update timestamp

Relations

• organization_id → organization.id
• project_id → project.id
• figma_file_key — the Figma file key; joins to the design (type=component) rows and design_component docs of components swept from this file.
• No direct relation is enforced inside DocumentDB; relations are logical and validated by application code.

Indexes

• PRIMARY KEY (_id)
• UNIQUE (organization_id, project_id, figma_file_key) — one bookkeeping doc per project file
• Secondary index on role (organization_id, project_id, role) — component_sweep scopes its walk to a project's registered files (working + library roles)

Type Codes

role

• 0: working (generation output file)
• 1: library (component/rule source)

Notes

• Two disjoint writers, no conflict. The plugin file-registration writes role / config_url through wf2des-api; component_sweep writes components_synced_at, sweep_error, style_captures, and sweep_marker directly. The writes are field-level and never overlap.
• sweep_marker is the single-flight guard for component_sweep — acquired at the start of a sweep and released/expired at the end; a marker past expires_at is reclaimable (crash-safe stale-lock recovery).
• components_synced_at is updated LAST, only after the sweep completes, so it doubles as the run-freshness signal for otherwise ledger-free internal runs.
• style_captures is the single source of the derived spec style_bindings map produced during the assemble phase; it was relocated here from design_component so there is exactly one capture set per figma_file_key.
• config_url points at the per-project config.json; the assemble worker reads it to resolve design_generation_result.placement.design_area (the plugin never reads project config directly).
• Only created_at / updated_at audit columns — no soft-delete (no deleted_at). Component removal is recorded on the platform design row's status, not here.
• This collection intentionally omits the shared lineage envelope that the other five wf2des collections carry: it has two disjoint writers and no single producing run, so provenance is per-field (components_synced_at / sweep_error) plus index_schema_version, not a run-scoped envelope.