Combo Templates

Overview

Combo templates prescribe future creative tests. Each combo template defines a combo type, product line, audience, and optional Canva design link. Combo templates feed into the suggestion generation and combo report workflows.

Goal: Maintain a library of combo templates that standardize how new creative tests are defined.

API endpoints

Combo templates are stored as macrodata_artifact rows with kind=combo_template. Both low-level and workflow APIs apply:

Method	Path	Spec	Description
GET	/macrodata-catalogs/{catalog_id}/artifacts?kind=combo_template	macrodata.yaml	List combo templates in a catalog
GET	/macrodata-artifacts?kind=combo_template	macrodata.yaml	List combo templates across catalogs
POST	/macrodata-artifacts	macrodata.yaml	Create combo template artifact
GET	/macrodata-artifacts/{artifact_id}	macrodata.yaml	Get combo template detail
PUT	/macrodata-artifacts/{artifact_id}	macrodata.yaml	Update combo template
DELETE	/macrodata-artifacts/{artifact_id}	macrodata.yaml	Archive combo template

Schema tables

Table	Role
macrodata_catalog	Catalog/namespace grouping combo template artifacts
macrodata_artifact	Stores combo templates (kind=combo_template)
link_product_macrodata_artifact	Links products to combo template artifacts

Infrastructure

Resource	Purpose
Internal Worker (CF Worker)	Serves CRUD endpoints behind CF Access
PlanetScale (Postgres via Hyperdrive)	Primary data store

Participants

Actor	Role
Staff user (Creative)	Creates, browses, and deletes combo templates
Dashboard API Worker	Serves CRUD endpoints
PlanetScale	Data store for combo templates

Combo template identifier convention

Combo template identifiers follow the same structured format as combo report identifiers:

{type}-{productCodes}-{productCount}-{audience}-{sequenceNumber}

Examples:

• SP-IPH-2-WOMEN-001 — first static post combo template, 2 iPhone products, women audience
• CT-IPH+SAM-3-MEN-002 — second carousel combo template, 3 mixed products, men audience

Product codes

Code	Product line
IPH	iPhone cases
SAM	Samsung cases
GRIPZ	Grip cases
AIR	AirPod cases
AIRMAX	AirPod Max cases

When multiple product lines are selected, codes are sorted alphabetically and joined with + (e.g., AIR+IPH).

Combo types

Code	Type
SP	Static Post
CT	Carousel Template
NT	New Template
UGC	User-Generated Content
ST	Story Template

Sequence numbering

The sequence number is auto-generated by querying existing combo templates with the same prefix and incrementing the highest found number (3-digit padded: 001, 002, etc.).

Create request DTO

interface CreateComboTemplate {
  label: string | null;        // optional human-readable name
  type: "SP" | "CT" | "NT" | "UGC" | "ST";
  product_count: number;       // number of products in the combo
  audience: "WOMEN" | "MEN";
  canva_url: string | null;    // link to Canva design asset
  product_codes: string[];     // e.g. ["IPH", "SAM"]
}

The combo template identifier is auto-generated server-side from the type, product codes, count, audience, and next available sequence number.

Database table

The underlying macrodata_artifact row uses these columns:

Column	Type	Description
id	UUID	Primary key
name	VARCHAR(255)	Combo template display name
config	JSONB	Template configuration and design specifications
temporal_origin	TIMESTAMPTZ	Creation timestamp
last_modified_at	TIMESTAMPTZ	Last update timestamp

Migration notes

The current system accesses combo_templates directly via the Supabase client from the frontend (no Express route). In the rewrite, this becomes a proper API route in the Dashboard API Worker, following the same pattern as combo reports.

Acceptance criteria

• Combo template identifier is correctly auto-generated following the convention
• Multiple product codes are sorted and joined with +
• Sequence numbers increment correctly and avoid collisions
• Combo templates can be listed, created, and deleted
• Deleting a combo template does not affect combo reports that reference its identifier