RPS Digital Intake Dossier

Source Summary

Project Intake - RPS Digital ## 1) Executive Summary RPS Digital is a digital-only e-commerce storefront for selling downloadable products (instant delivery) with a headless CMS and a secure fulfillment/download pipeline. - Storefront: Next.

Imported Context

Project Intake - RPS Digital

1) Executive Summary

RPS Digital is a digital-only e-commerce storefront for selling downloadable products (instant delivery) with a headless CMS and a secure fulfillment/download pipeline.

• Storefront: Next.js App Router + Tailwind UI, deployed on Vercel
• Catalog/CMS: Sanity (products, categories, collections, pages, homepage builder)
• Checkout/Fulfillment: Stripe Checkout + webhook-driven order creation, download token issuance, and email delivery
• Downloads: Private file storage in Google Cloud Storage (GCS) with signed URLs and per-purchase download limits
• Auth: Clerk is present in code (middleware + /sign-in and /sign-up routes); some documentation still references prior NextAuth work

2) Project Type and Domain

• Type: Digital product e-commerce (headless CMS + storefront)
• Domain: Digital downloads (licenses, secure download links, customer portal)
• Primary users:
  • Shoppers: browse → buy → download
  • Admins/content managers: manage catalog, homepage blocks, promos, SEO metadata in Sanity Studio

3) Repository and Live URLs

• Repo: https://github.com/maggielerman/rps-digital
• Live: https://rps-digital.com
  • Note: redirects to the www host for many routes (example: https://www.rps-digital.com)
• Sanity Studio (hosted): https://rpsdigital.sanity.studio
• Google Merchant feed (live):
  • XML: https://rps-digital.com/api/feeds/google-merchant
  • JSON: https://rps-digital.com/api/feeds/google-merchant?format=json

4) Product/User Journey Summary

• Browse: Home → Products / Categories / Collections → Search
• Evaluate: Product detail page (/product/[slug]) with digital-product details (format/license/instant download messaging)
• Purchase: Cart (/cart) → Checkout (/checkout) via Stripe Checkout session creation (/api/checkout)
• Fulfillment: Stripe webhook (/api/webhooks/stripe) creates Order + OrderItems in Postgres and issues Download records + (optional) License keys
• Access downloads:
  • Success page (/success) + customer portal (/my-orders) for lookup and download access
  • Download endpoint (/api/download/[token]) signs a GCS URL on-demand and tracks download counts/limits

5) Architecture and Stack Summary

• Frontend/Server: Next.js (App Router), React, TypeScript
• Styling/UI: TailwindCSS (+ Radix UI components in deps)
• State: Redux Toolkit
• CMS/Catalog: Sanity (Next Sanity integration via next-sanity)
  • Sanity webhooks trigger Next.js cache revalidation (src/app/api/webhooks/sanity/route.ts)
• Database (transactions): PostgreSQL via Prisma ORM (prisma/schema.prisma)
  • Stores orders, downloads, licenses, customers, preview sessions/analytics
• Payments: Stripe Checkout + webhook processing
• File storage: Google Cloud Storage private bucket + V4 signed URLs (src/lib/gcp-storage.ts)
• Auth: Clerk middleware (src/middleware.ts) + webhook endpoint (src/app/api/webhooks/clerk/route.ts)
• Deployment: Vercel (GitHub Actions deploy workflow), plus CI workflows for drift detection and scheduled sync

Data ownership (per project docs):

• Catalog source of truth: Sanity (products, categories, collections, pages, homepage config)
• Transaction source of truth: Postgres/Prisma (orders, downloads, licenses, customers)

6) Key Workflows and Operational Flows

A) Storefront purchase + fulfillment

• POST /api/checkout → creates Stripe Checkout Session with product metadata
• Stripe event checkout.session.completed → POST /api/webhooks/stripe
• src/lib/order-fulfillment.ts:
  • createOrder() persists Order/OrderItem snapshots
  • generateDownloadLinks() creates Download tokens (30-day expiry, default max 5 downloads) and sends transactional emails
  • Integrates with Sanity to map purchased SKUs to stored GCS object keys (bundle + per-asset “dual-mode” downloads)

B) Secure download access

• GET /api/download/[token]:
  • Validates token without consuming usage
  • Signs a 24-hour GCS URL for the stored object key
  • Consumes a download attempt only after signing succeeds
  • Navigation requests are 302-redirected to the signed URL; API callers receive JSON

C) Content + marketing ops

• Sanity page builder/homepage blocks and scheduling (see Content Manager + Marketing Automation docs)
• Webhook revalidation maps document types (product/category/release/homepage/features) to path revalidation

D) SEO + discovery

• Product JSON-LD + next-seo configuration
• Google Merchant Center feed at /api/feeds/google-merchant
• next-sitemap runs during build (npm run build)

E) CI/CD + drift protection

• GitHub Actions workflows:
  • CI pipeline: schema validation/drift detection + unit + e2e + security checks
  • Scheduled schema drift detection (daily 2 AM UTC) and database/Sanity sync jobs
  • Vercel deploy workflow for main

F) Digital asset generation pipeline (adjacent subproject)

• external-integrations/digital-product-pipeline/ contains an n8n/ImageMagick/Puppeteer pipeline for generating wall-art assets + PDFs, uploading to GCS/S3, and registering in CMS.

7) AI Context: Prompts, Chats, Agent Workflows

In-repo agent guidance

• Agent instructions: ../../Agents.md
• Consolidated docs index for agents: ../../.zencoder/rules/repo.md

Agent/ops helper scripts

• Changelog timestamp/header utilities: ../../scripts/changelog-utils.js
• Changelog entry helper: ../../scripts/add-changelog-entry.js
• Handoff document utilities: ../../scripts/handoff-utils.js
• Interactive handoff creator: ../../scripts/create-handoff.js

AI prompting artifacts (pipeline subproject)

• CSV prompting guide (Cursor): ../../external-integrations/digital-product-pipeline/scripts/csv_optimization_prompting_guide.md
• Optional OpenAI-assisted CSV optimizer script: ../../external-integrations/digital-product-pipeline/scripts/optimize_csv_content.js
• Agent handoff doc (pipeline): ../../external-integrations/digital-product-pipeline/AGENT.md

Local IDE plugin metadata (potentially sensitive)

• .idea/zencoder-chat-index.xml appears to index AI chat sessions (metadata only). Consider excluding from import if hyphenomenon should avoid ingesting developer-local AI artifacts.

8) Supporting Docs and External Resources

Core project docs

• Repo overview: ../../README.md
• Project status: ../../DOCS/project-master.md
• Roadmap: ../../DOCS/ROADMAP.md
• Changelog: ../../DOCS/CHANGELOG.md
• Technical reference: ../../DOCS/technical-reference.md
• Testing/CI: ../../DOCS/testing-and-ci.md

Operational guides

• Deployment: ../../DOCS/deployment-guide.md
• Content manager guide (homepage/page builder): ../../DOCS/content-manager-guide.md
• Marketing automation (scheduling/seasonality): ../../DOCS/marketing-automation.md
• GCP/GCS integration setup: ../../DOCS/gcp-integration-setup.md
• Clerk status + checklist: ../../DOCS/clerk-implementation-status.md

Key implementation entry points (code)

• Stripe webhook fulfillment: ../../src/app/api/webhooks/stripe/route.ts
• Order + download generation: ../../src/lib/order-fulfillment.ts
• Download signing endpoint: ../../src/app/api/download/[token]/route.ts
• GCS signing + uploads: ../../src/lib/gcp-storage.ts
• Sanity revalidation webhook: ../../src/app/api/webhooks/sanity/route.ts

9) Screenshot Gallery (with relative links + captions)

#	File	Caption
01	screenshots/01-home.png	Home / landing (marketing + discovery entry)
02	screenshots/02-products.png	Products listing (primary browsing workflow)
03	screenshots/03-product-detail.png	Product detail page (key decision/detail screen)
04	screenshots/04-cart.png	Cart (purchase workflow)
05	screenshots/05-my-orders.png	Customer portal / order lookup (post-purchase downloads)
06	screenshots/06-studio.png	Admin equivalent: embedded Sanity Studio route (/studio, signed-out view)

10) Candidate Import Nodes and Relationships

Project supernode

• Label: RPS Digital
• Suggested slug: rps-digital

Major node candidates

• Repo
  • rps-digital (repo) → https://github.com/maggielerman/rps-digital
• Live application
  • RPS Digital (live site) → https://rps-digital.com
• CMS
  • Sanity Studio (RPS Digital) → https://rpsdigital.sanity.studio
• Core systems
  • Storefront (Next.js App Router)
  • Checkout & Fulfillment (Stripe Checkout + webhook)
  • Orders/Downloads/Licenses (Prisma + Postgres)
  • Secure Downloads (GCS signed URLs)
  • Authentication (Clerk)
  • SEO + Feeds (next-seo, next-sitemap, Google Merchant feed)
  • Navigation/Megamenu system (/api/navigation, /api/megamenu)
  • Preview system + analytics (PreviewSession, PreviewAnalytics, /api/preview/*, /api/analytics/*)
• Docs
  • Project Master, Roadmap, Changelog, Technical Reference, Testing & CI, Deployment Guide, Marketing Automation Guide, Content Manager Guide
• AI/agent artifacts
  • Agents.md (agent instructions)
  • Changelog utilities
  • Handoff utilities
  • Digital product pipeline (n8n/ImageMagick/Puppeteer) (subproject)
  • CSV optimization prompt + optional OpenAI script (subproject)

Likely relationships (edges)

• RPS Digital → HAS_REPO → rps-digital (repo)
• RPS Digital → DEPLOYED_AS → RPS Digital (live site)
• RPS Digital → USES_CMS → Sanity Studio (RPS Digital)
• Storefront (Next.js App Router) → DEPLOYS_TO → Vercel
• Checkout & Fulfillment → USES → Stripe
• Secure Downloads → USES → Google Cloud Storage
• Orders/Downloads/Licenses → PERSISTS_IN → PostgreSQL (Neon) (if still the current provider; docs indicate Neon)
• SEO + Feeds → PROVIDES → Google Merchant Center feed
• Docs → DOCUMENT → (Architecture, Operations, Content workflows, Testing/CI)
• AI/agent artifacts → GUIDE_WORK → (Changelog entries, Handoffs, Pipeline optimization)

11) Risks, Gaps, and Unknowns

• Auth/docs mismatch: Codebase uses Clerk middleware and routes; several docs still mention NextAuth. Treat current auth architecture as Clerk unless re-verified.
• Secrets/sensitive files present in working tree (should be excluded from import if hyphenomenon ingests full filesyst

...[truncated for intake]

Provenance

• Source file: rps-digital/DOCS/intake/hyphenomenon-project-intake.md
• Source URL: https://github.com/maggielerman/rps-digital/blob/main/DOCS/intake/hyphenomenon-project-intake.md