Scenarios Overview

These scenarios follow the OAGi ConnectSpec pattern — each defines participants, assumptions, a business workflow, and exception handling. They serve as the Operational Analysis (OA) layer in the Arcadia method, directly traceable to logical components and physical infrastructure.

Each scenario page includes:

• API endpoints — concrete paths mapped to OpenAPI specs
• Schema tables — PlanetScale tables read or written
• Infrastructure — CF Workers, Pipelines, Queues, and storage involved
• Participants — actors and services
• Workflow steps — the main success path and exception handling

Scenario catalog

Data pipelines (workflows)

Scenario	Trigger	Primary actors	Key tables / storage	What it does
Daily Shopify Bulk Sync	Cron (daily) or manual	Cron, CF Workflow, Shopify API	order_header, order_line_item, product (PG); sync.telemetry (R2); watermarks in DO	Acquires order data and streams to pipelines
Product Tag Sync	Manual (“Sync Tags”)	Staff, CF Workflow, Shopify API	product, product_tag	Updates product attributes (tags, vendor, status)
Asset Ingest	Staff submits artifact + URL	Staff, CF Workflow, Dropbox, R2, Shopify	macrodata_artifact (kind: design_asset), link_product_macrodata_artifact	Ingests design assets to R2, links to products
CSV Export	Staff requests export	Staff, CF Workflow, R2	macrodata_artifact (kind: document_export), order_header	Generates downloadable export file
Fulfillment Monitoring	Read-only (data from daily sync)	Fulfillment team	fulfillment_daily_summary	Daily fulfillment metrics (success/failure rates)

Analytics & classification

Scenario	Trigger	Primary actors	Key tables / storage	What it does
Performance Metrics	Browsing + settings	Ops/Creative, Dashboard API	measurement.performance (R2 Iceberg), macrodata_artifact (kind: classification_spec)	Metrics retrieval; classification thresholds govern tier assignment
Tag Analytics	Browsing + refresh	Creative/Ops, Dashboard API	product, measurement.sales (R2 Iceberg), product_tag	Aggregated sales metrics by tag
Tag Groups	Staff creates/edits groups	Creative/Ops, Dashboard API	product_category	CRUD on tag group collections
Tag Classification	Staff bulk-classifies tags	Staff, Dashboard API	product_tag	Assigns tags to product collections
Designer Assignment	Staff assigns tags to designers	Creative lead, Dashboard API	macrodata_artifact (kind: agent_assignment), product, measurement.sales (R2)	Links designers to tags for sales attribution

Combo management

Scenario	Trigger	Primary actors	Key tables / storage	What it does
Combo Log CRUD	Staff creates/imports combos	Staff, Dashboard API	macrodata_artifact (kind: combo_report)	Report lifecycle management
Combo Templates	Staff manages template library	Creative, Dashboard API	macrodata_artifact (kind: combo_template)	Template library with action specs
Combo Suggestions	Staff requests generation	Staff, CF Workflow	macrodata_artifact (kinds: combo_suggestion, combo_report), measurement.performance (R2)	Auto-generates combo suggestions with confidence scores

Lookup

Scenario	Trigger	Primary actors	Key tables / storage	What it does
Order Lookup	Staff searches by ID/name	Staff, Dashboard API	order_header, order_line_item	Search and retrieve order records

API endpoints matrix

Scenario	Endpoints	Auth
Bulk Sync	POST /api/performance-metrics/sync, GET /api/ingest/runs, GET /api/health	CF_ACCESS
Tag Sync	POST /api/products/tags/sync, GET /api/products/tags/sync/status	CF_ACCESS
Performance Metrics	GET/POST/PUT/DELETE /api/performance-metrics, GET /api/performance-metrics/stats/summary, GET/PUT /api/performance-metrics/settings/classification	CF_ACCESS
Tag Analytics	POST /api/tag-analytics/performance, GET /api/tag-analytics/distribution/:category, GET /api/tag-analytics/group-performance/:groupId, POST /api/tag-analytics/refresh	CF_ACCESS
Tag Groups	GET/POST /api/tag-groups, DELETE /api/tag-groups/:groupId	CF_ACCESS
Tag Classification	POST /api/tag-classifications/bulk, GET /api/tag-classifications/unclassified	CF_ACCESS
Designer Assignment	GET /api/designers, GET /api/designers/names, POST /api/designers/assign, DELETE /api/designers/unassign, DELETE /api/designers/:designerName	CF_ACCESS
Combo CRUD	GET/POST /api/combo-logs, PUT/DELETE /api/combo-logs/:id, POST /api/combo-logs/import, GET /api/combo-logs/export	CF_ACCESS
Combo Templates	GET/POST /api/combo-templates, DELETE /api/combo-templates/:templateId	CF_ACCESS
Combo Suggestions	POST /api/combo-suggestions/generate, GET /api/combo-suggestions, POST /api/combo-suggestions/:id/accept	CF_ACCESS
Asset Ingest	POST /api/assets/ingest, GET /api/assets/:productId, GET /api/assets/status/:productId	CF_ACCESS
CSV Export	POST /api/csv/generate, GET /api/csv/exports, GET /api/csv/exports/:id	CF_ACCESS
Order Lookup	POST /api/orders/lookup	CF_ACCESS
Fulfillment	GET /api/fulfillment-daily-summary	CF_ACCESS

Cross-scenario standards

Authentication

All endpoints are staff-only, protected by Cloudflare Access. JWT validation uses the Cf-Access-Jwt-Assertion header (cookie is not guaranteed).

Workflow semantics

Scenarios using CF Workflows for workflow execution (ProcedureExecution) dispatch assume:

• Durable step tracking with automatic retries and replay
• Watermark state in Durable Object persistent storage
• Execution audit trail via SYNC_TELEMETRY Pipeline → sync.telemetry on R2
• Error events emitted to sync telemetry for long-term retention

Database batching

All PG domain writes must respect PlanetScale limits: 100k rows per statement, 64 MiB result size, 20s transaction timeout.

Operational scripts (not scenario-scoped)

These one-time or maintenance workflows exist in the codebase but don’t warrant standalone scenarios:

Script	Purpose	Frequency
Shopify OAuth callback	One-time token exchange for permanent offline access	Once
Asset backfill	Batch-process existing Dropbox links into R2 objects	One-time migration
Metafield audit	Compare Dropbox links vs product-asset links	Ad-hoc diagnostic
Asset retry / cleanup	Retry failed Workflows, fix content types, delete old artifacts	Ad-hoc maintenance