Shopify Headless Storefront

Narrative

01

Storefront As Operating System

Shopify Headless Storefront is not only a front-end replacement for a Shopify theme. The source repo couples the public Rock Paper Scissors shopping experience with the operator proof system around it: catalog review boards, media ledgers, cutover packets, blog quality rules, and project checkpoints. The core decision was to use a headless app because Shopify-hosted themes were limiting campaign, SEO, content, and programmatic landing-page iteration speed, while preserving Shopify checkout as the compliant commerce boundary.

02

Evidence Before Live Mutation

The project repeatedly separates analysis, review, apply, and verification. Catalog changes start with numbered review boards and human notes; cutover work runs repeatable preflight/master-pack commands; media uploads are tracked through a generated ledger; and blog remediation keeps Shopify Admin mutations tied to public HTML and link/media verification. That constraint matters because the system touches live commerce and editorial surfaces: AI and scripts can accelerate audits, mockups, and apply plans, but human review and post-apply proof remain first-class artifacts.

03

Blog Audit Thread Attachment

Codex chat 019e45cf belongs to this project because it proved a concrete slice of the storefront operating loop. The thread audited Shopify-backed public blog content, pivoted to live HTML when API access was unavailable, separated article content from feature media, and carried the approved Anna Atkins mockup into production verification. The useful lesson is not just that one article image changed; it is that content quality, semantic link quality, media relevance, and headless layout behavior all need their own evidence lanes.

System surfaces

Production Storefront

shoppers

Public Rock Paper Scissors storefront at `https://www.rockpaperscisso.rs`, including homepage, navigation, review surfaces, catalog entry points, and checkout handoff.

Shopify Catalog And Product Pages

shoppers and operator

Shopify-backed collection and product pages expose catalog, product media, pricing, product cards, quick add, reviews, and purchase pathways through the headless app.

Blog And Article System

readers, search visitors, and operator

Shopify-backed `/blogs*` routes render article content from Shopify while the headless app owns layout, link previews, companion rails, structured data, redirects, and cache behavior.

Agentic Catalog API

agent clients and engineering

Feature-flagged `/api/agents/catalog` and `/api/agents/checkout` endpoints provide controlled catalog retrieval and checkout preparation for external agents under explicit mode and origin gates.

Cutover And Catalog Evidence System

operator and reviewer

Repo-native evidence packets, catalog review boards, media ledgers, and cutover master packs make live storefront and catalog work auditable.

Implementation stack

Storefront Runtime

• Next.js App Router
• React
• TypeScript
• Tailwind CSS
• Radix UI
• Playwright

Commerce And Content

• Shopify Storefront API
• Shopify Admin GraphQL
• Shopify Customer Account API
• Judge.me reviews
• Google Merchant feed

Proof And Operations

• repo-native Markdown docs
• cutover preflight/master-pack scripts
• catalog review boards
• product-media ledger
• SEO/GEO and parity audits

Evidence

20 artifacts grouped by type so each kind of proof can be scanned on its own.

The public app maps Shopify products, variants, collections, menus, blogs, articles, cart lines, checkout URLs, reviews, feeds, and customer-account state into customer-facing routes and machine-readable endpoints.

13 entities1 proof

Workflows

1 artifact

workflowMay 23, 2026

Shopify Headless evidence-gated storefront operations

How the Shopify Headless project moves from issue, content audit, catalog review, or cutover need into live storefront change: inspect source and production state, create reviewable evidence artifacts, get human/operator approval for live Shopify or deploy mutations, apply bounded changes, and verify public routes plus repo evidence afterward.

7 steps1 record

Images

4 artifacts

image

Production storefront homepage at `https://www.rockpaperscisso.rs/`.

image

Shopify product detail page with customer-facing product media and purchase pathway.

image

Shopify-backed blog article surface connected to project `1110` and the `019e45cf` audit/remediation context.

image

Shopify-backed collection surface at `/collections/wall-art`.

Chats

3 artifacts

chatJul 11, 2026

Customer Email Automation Audit and Cleanup

Codex operations thread that mapped every transactional, marketing, delivery, and review email associated with Rock Paper Scissors orders; identified overlapping Trustpilot, Judge.me, Shopify, Flow, and RPS Digital sequences; executed the approved retail cleanup; preserved wholesale transactional communication; and started controlled zero-dollar QA orders for end-to-end cadence proof.

1 chat

chatJun 30, 2026

Shopify B2B Trade Portal and Catalog Operations

Codex build and operations thread that proved Shopify's native market-scoped B2B catalog model on the current plan, implemented a gated headless trade portal and interactive wholesale PDP over the existing retail catalog, propagated company-location buyer identity through cart and checkout, corrected route-level access control, created the first CDX-prefixed live print product, and migrated every exact Posters-category product to Prints without changing other merchandising fields.

1 chat

chatMay 20, 2026

Shopify Headless Blog Audit and Anna Atkins Remediation

Codex thread that audited Shopify-backed RPS blog articles, checked link/media quality, and carried the approved Anna Atkins hero/mockup remediation through production verification.

1 chat

Source Summary Brand image artifact for the Rock Paper Scissors production storefront identity. Imported Context This image source is the public RPS primary...

1 topic1 scope

Connected references

Customer Email Automation Audit and Cleanupchat · 1 edge →Shopify B2B Trade Portal and Catalog Operationschat · 1 edge →Shopify Headless Blog Audit and Anna Atkins Remediationchat · 1 edge →

Key dates

2026-03-09

MVP product baseline

Product brief and PRD defined the headless storefront goal, Shopify checkout boundary, analytics expectations, and fast landing-page iteration need.

2026-04-19

Cutover evidence system

Cutover docs established repo-canonical preflight, compare, and master-pack artifacts for launch-window proof.

2026-05-20

Blog audit and Anna remediation thread

Codex chat 019e45cf audited public Shopify blog content and carried an approved Anna Atkins mockup into production verification.

2026-05-23

Hyphenomenon reintroduction

Project 1074 reintroduced Shopify Headless with packet-backed project evidence and preserved the related chat edge.