UXR Canonical Data and Public Projection Architecture

Architecture status

Adopted and operational for new UXR development. Notion is the canonical development environment for UXR's evolving schema, documentation, field contracts, project-development records, and publication-control metadata. Shopify remains the public website, storefront, SEO surface, and derived publication layer.

Canonical source

Canonical UXR meaning is authored and maintained in Notion. Database properties preserve structured facts and governance state; the Notion page body is the authoritative current body of a documentation record.

Shopify Metaobject IDs, Article IDs, and theme resources are implementation mappings. They do not replace stable UXR identifiers.

Public projection

Shopify should receive only the publication-safe fields necessary to render the public UXR experience. Public projection objects are derived records and must not become the editing source for canonical UXR meaning.

For documentation, the intended public projection includes stable document identity, approved title and summary, approved body, public document type, public version/revision, publication dates, change summary, discussion question when appropriate, navigation relationships, and synchronization metadata.

Private material does not inherit public eligibility

Private evidence, unredacted screenshots, contributor-identifying material, internal notes, full revision history, migration notes, reviewer-only analysis, field-contract instructions, intake workbench records, private dashboards, and other restricted content remain in the canonical layer unless separately reviewed and approved for a specific public projection.

A relation to a public record never creates publication consent for a private record.

Documentation history

Current document text and historical revision are separate concerns. UXR Documentation stores the current canonical document and its governance/publication metadata. UXR Documentation Revisions & Change Log stores append-only substantive revisions, corrections, authority changes, migrations, milestones, and publication impact.

UXR Development Items & Capabilities separately records what UXR itself is building, why it exists, what demonstrably works now, known limitations, planned functionality, and future direction.

Field semantics

Short property descriptions provide immediate local instructions. UXR Schema Dictionary & Field Contracts provides the longer authoritative semantic contract for important fields, including purpose, requiredness, cardinality, anti-inference boundaries, privacy treatment, public-export behavior, examples, and anti-examples.

A schema change is incomplete until affected field contracts and governing documentation are updated where the change alters meaning.

Migration discipline

Legacy Shopify records are migration sources, not automatically canonical after import. Each documentation record carries an explicit migration state. Metadata-only imports remain incomplete. A document becomes Canonical Verified only after its current body and material metadata have been reconciled sufficiently to serve as UXR's source of truth.

Legacy Shopify IDs and paths are preserved for lineage, redirects, and reconciliation.

Delta publication

The publication path compares an approved canonical public payload with the last successfully synchronized payload. If the deterministic payload hash is unchanged, no Shopify write should occur. If it changed, the publisher should update or create the public projection, read it back, record the new hash/version/time, and append an operational sync record.

Publication failures must preserve their actual class: application safety block, Shopify platform limit, schema/API error, validation failure, or readback mismatch should not be conflated.

Server-side execution

The publication process is intended to run in a cloud/server execution environment rather than on the founder's local computer. Manual publication remains available for testing and exceptional cases, but ordinary approved deltas should not depend on a desktop session.

Current implementation boundary

The Notion canonical documentation architecture, revision ledger, development registry, publication sync ledger, Entity foundation, field-contract structure, projection mapping, and publication controls are operational. The thin Shopify public-document schema has been created and read back successfully as uxr_public_document_v2 after an explicitly authorized retirement of an empty, superseded UXR definition freed one Shopify definition slot.

The new Shopify type is publication-only. It does not restore Shopify as the canonical documentation authoring layer. Storefront cutover remains gated on publication of a small verified specimen set, rendering against an unpublished theme, and one successful manual delta/write/readback cycle.

Cutover rule

Shopify remains the public source served to visitors until the new projection path is validated. Notion becomes canonical for a migrated document only when its migration state is Canonical Verified. Public cutover follows successful projection, storefront rendering, readback, and privacy/reconciliation checks—not merely the existence of a Notion row.