Mantra Seeds

Off-the-shelf commerce platforms can't handle a regulated vertical: the catalog needs age-gating, payments must run through Square rather than the default Stripe path, and the brand wants reviews, wishlists, search, invoices, and email that behave like a first-party product, not bolted-on plugins. A headless build was the only way to own every one of those surfaces.

A Vercel-Commerce-derived Next.js 16 / React 19 storefront on a heavily extended Medusa v2 backend. Nine custom Medusa modules, ~18 subscribers, ~30 workflows, and five module links sit behind a provider-agnostic checkout shell. Square runs as the active payment provider through a hand-written AbstractPaymentProvider; Stripe stays as the template fallback. The storefront layers an optimistic cart drawer, multi-step checkout, Meilisearch search with a Cmd+K palette, on-demand React-PDF invoices, and a WebGL/GSAP motion system on top.

• 01

  Nine custom Medusa v2 modules — product-review (verified-purchase + admin responses), wishlist (guest + share tokens), invoice, newsletter, presence, resend, meilisearch, product-media, and square-payment — plus ~18 subscribers, ~30 workflows, custom admin widgets/routes, and five module links

• 02

  Hand-written Square payment provider extending Medusa's AbstractPaymentProvider: full initiate/authorize/capture/cancel/refund/getStatus lifecycle, HMAC webhook signature verification, BigNumber money handling, Sentry + PostHog instrumentation, and unit + sandbox tests

• 03

  Meilisearch product search wired to a Cmd+K command palette, with a provider-agnostic checkout shell decoupling the UI from Square vs. Stripe

• 04

  On-demand React-PDF invoice generation rendered from order data through a dedicated Medusa workflow

• 05

  WebGL/OGL circular gallery and GSAP motion system, a CSP nonce proxy, Zod-validated server actions, PII redaction, feature flags, and age-gating for a regulated vertical

• 06

  Transactional email + newsletter (Resend Audience + Buttondown) with an HMAC-signed abandoned-cart recovery cron

• A working headless storefront and admin: full catalog and PDPs, an optimistic cart drawer, multi-step checkout, customer accounts, reviews, and wishlists all run on the custom Medusa backend.
• Square is the live payment path through the hand-written provider — initiate through refund plus signature-verified webhooks — with Stripe retained behind the same provider-agnostic checkout shell as a fallback.
• Roughly 740 TypeScript/TSX files and 122 test files across the storefront and backend, covering the Square provider money math, webhook handling, and the checkout golden path.

• Next.js 16
• React 19
• TypeScript
• Medusa v2
• Square
• Stripe
• Meilisearch
• PostgreSQL
• Redis
• React-PDF
• Resend
• Buttondown
• OGL
• GSAP
• Zod
• Sentry
• PostHog
• Playwright
• Vitest

Production client build — headless commerce for a regulated vertical.

Deep headless-commerce engineering: extending Medusa v2 with custom modules, workflows, subscribers, and admin UI; writing a payment provider from scratch against the AbstractPaymentProvider contract with webhook verification and money-precision handling; a bespoke tokenized design system with sophisticated WebGL/GSAP motion; and rigorous production practices — Zod validation, PII redaction, CSP, instrumentation, and a real test suite. No LLM/AI in the product; agentic commerce was explicitly deferred.

The interesting work in headless commerce isn't the storefront — it's the backend you have to build to make the storefront honest. A payment provider written against an abstract contract lives or dies on money precision and webhook verification, and most of the engineering went into the nine custom modules and ~30 workflows that the UI just reads from.

7 min read