Product Tag Sync

Overview

Refresh product tags, vendor, and status from Shopify into material_artifact.tags — updating the Qualities (BFO) of MaterialArtifacts (IOF) to power tag analytics and UI filters, without requiring a full data acquisition ProcedureExecution.

Goal: Ensure MaterialArtifact Quality accuracy independently of the daily bulk sync.

Participants

Actor	Ontological type	Role
Staff user (Ops/Creative)	Person (CCO) bearing Role (BFO)	Triggers sync via UI
Dashboard API Worker	EngineeredSystem (IOF)	Validates, enqueues job
Ingest Worker	EngineeredSystem (IOF)	Fetches tags, upserts MaterialArtifacts
Shopify Admin API	External EngineeredSystem (IOF)	MaterialArtifact data source

Main success scenario

[CCO: Act updating Qualities on MaterialArtifacts]

1. Person bearing Operations/Creative Role clicks “Sync Tags” → POST /api/products/tags/sync
2. API writes optional procedure execution record and enqueues ARTIFACT_TAG_SYNC
3. Ingest Worker queries Shopify (prefer GraphQL) with rate-limit backoff
4. Worker upserts material_artifact(tags, vendor, status, last_seen) in chunks — updating Qualities on each MaterialArtifact
5. Worker optionally enqueues measurement dataset refresh if Nominal Classification depends on tags

Exception flows

IssueOccurrence	FallbackStep
Shopify rate limit	Delay retry using queue delaySeconds (up to 12 hours)
PlanetScale limits	Use smaller batches

Queue contract

{
  "job_type": "ARTIFACT_TAG_SYNC",
  "job_id": "uuid",
  "mode": "full",
  "requested_at": "ISO8601"
}

API endpoints

• POST /api/products/tags/sync — enqueue (p99 < 200ms)
• GET /api/products/tags/sync/status?job_id=... — optional status check

Acceptance criteria

• PASS: Sample MaterialArtifact’s tags in Shopify match material_artifact.tags after completion
• FAIL: Orphaned MaterialArtifacts, malformed JSON in tags, or job unable to complete