This is the engineering handoff that described the target backend shape. It remains the authoritative reference for the data model, integration surface, and end-to-end fulfillment flow.

The shape of things

Three tiers: the storefront, a custom Node service for configurator state + AI jobs, and Shopify for the classic commerce primitives (cart, checkout, payments, tax, fraud). Ops uses this console; customers see accounts via Shopify Customer Account API.

Schema (SQLite · owned by us)

-- Pin SKUs (a tiny product catalog mirrored from Shopify)
CREATE TABLE pins (
  id                TEXT PRIMARY KEY,
  category          TEXT NOT NULL,
  label             TEXT NOT NULL,
  glyph             TEXT,
  image_url         TEXT,
  base_price_cents  INTEGER NOT NULL DEFAULT 300,
  created_at        TEXT DEFAULT (datetime('now'))
);

-- Finishes (silver/gold/black/rose) with per-SKU inventory
CREATE TABLE pin_variants (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  pin_id        TEXT REFERENCES pins(id),
  finish        TEXT NOT NULL,
  bay_location  TEXT,
  stock_qty     INTEGER NOT NULL DEFAULT 0,
  reorder_point INTEGER NOT NULL DEFAULT 20,
  UNIQUE(pin_id, finish)
);

-- User's configurator state, one row per saved design
CREATE TABLE designs (
  id            TEXT PRIMARY KEY,
  customer_id   TEXT,
  frame_color   TEXT NOT NULL,
  plate_text    TEXT,
  finish        TEXT NOT NULL DEFAULT 'silver',
  placements    TEXT NOT NULL,   -- JSON { "0": { pin, finish }, ... }
  thumbnail_url TEXT,
  version       INTEGER DEFAULT 1,
  created_at    TEXT DEFAULT (datetime('now')),
  updated_at    TEXT DEFAULT (datetime('now'))
);

-- Orders + event-sourced status audit
CREATE TABLE orders ( id PRIMARY KEY, design_id, customer_email, ship_address,
  subtotal_cents, tax_cents, shipping_cents, total_cents, status, tracking_number, ...);
CREATE TABLE order_events ( id, order_id, from_status, to_status, note, actor, created_at );

-- AI renders — one row per generate request
CREATE TABLE ai_preview_jobs ( id, design_id, provider, prompt, car_spec, status,
  progress, output_url, cost_cents, error, created_at, finished_at );

Endpoints exposed today

What we do NOT build ourselves

From click to doormat

1. Configurator autosaves placements to POST /api/designs every few seconds (debounced).
2. AI preview: user submits car spec → job queued → worker renders → MP4 to CDN → SSE progress to the UI.
3. Add to cart: API expands placements into Shopify variant_ids (one line per pin+finish), returns Shopify Checkout URL.
4. Checkout: Shopify handles payment, tax, fraud. Webhook orders/paid hits our service.
5. Order row created; email with AI preview sent; order appears in this console.
6. Pick: staff opens picklist → walks bays → scans each pin (decrements stock_qty).
7. Assemble: pins placed by hand, photographed for QC.
8. Ship: EasyPost buys cheapest label; tracking number written back.
9. Delivery webhook flips status; review email scheduled for +3 days.