Shopify Headless Storefront
Shopify Headless Storefront is the Rock Paper Scissors production storefront and operating system for Shopify-backed catalog, collection, product, cart, checkout-handoff, review, blog/article, feed, agentic-discovery, catalog-governance, and cutover-proof work. This reintroduction replaces the thin local fallback with source-backed project evidence and keeps the project attached to Codex chat 019e45cf-299f-7ae0-aff9-fef3a18f5d44, the blog audit and Anna Atkins remediation thread.
Narrative
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.
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.
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 design
System surfaces
Production Storefront
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
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
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
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
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
Artifacts
Agentic API Gate Model
External agent access is intentionally constrained by feature flags, catalog mode, checkout mode, allowed origins, path validation, Shopify token selection, and structured error contracts.
Cutover And Catalog Evidence Model
The proof system separates source docs, generated run manifests, summaries, compare CSVs, review-board manifests, media upload reports, product-media ledger outputs, and human approval checkpoints.
Storefront Commerce Model
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.
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.
Shopify Headless Storefront Intake Dossier
Shopify Headless Storefront is the Rock Paper Scissors production storefront and operating system for Shopify-backed catalog, collection, product, cart, checkout-handoff, review, blog/article, feed, agentic-discovery, catalog-governance, and cutover-proof work. This reintroduction replaces the thin local fallback with source-backed project evidence and keeps the project attached to Codex chat 019e45cf-299f-7ae0-aff9-fef3a18f5d44, the blog audit and Anna Atkins remediation thread.
README
Source Summary Rock Paper Scissors Headless Storefront Headless Shopify storefront built with Next. js App Router. Imported Context Rock Paper Scissors Headl...
product-brief
Source Summary title: Product brief: Shopify Headless Storefront description: One-page summary of user problem, MVP scope, and success metrics for the headle...
prd
Source Summary title: PRD: Shopify Headless Storefront (MVP) description: MVP requirements and constraints for the Shopify headless storefront implementation...
cutover-evidence-system
Source Summary title: Cutover Evidence System description: Repo-canonical workflow for preflight reruns, normalized compare output, master-pack generation, a...
catalog-review-workflow
Source Summary title: Catalog Review Workflow description: Standard operating pattern for numbered review boards, collaborative catalog cleanup, and audit-ba...
agentic-endpoints
Source Summary title: Agentic Commerce API Endpoints description: Feature-flagged catalog and checkout-prep API contracts for external agents. status: evolvi...
1110_blog-content-audit-and-remediation
Source Summary title: 1110 - Blog Content Audit and Remediation description: Audit and remediate current Shopify blog article quality, article media, article...
primary-logo-rps
Source Summary Brand image artifact for the Rock Paper Scissors production storefront identity. Imported Context This image source is the public RPS primary...
Visual evidence
Key dates
Product brief and PRD defined the headless storefront goal, Shopify checkout boundary, analytics expectations, and fast landing-page iteration need.
Cutover docs established repo-canonical preflight, compare, and master-pack artifacts for launch-window proof.
Codex chat 019e45cf audited public Shopify blog content and carried an approved Anna Atkins mockup into production verification.
Project 1074 reintroduced Shopify Headless with packet-backed project evidence and preserved the related chat edge.