Plan · Build · Sign-off

Babanuj → Hydrogen Port

Porting www.babanuj.com from Next.js 15 (Vercel) to classic Shopify Hydrogen — React Router 7 + Vite — hosted on Vercel, in a new repo, with a parity-gated cutover.

Reviewer

Claude (Fable 5)plans, reviews every PR, maintains this board

Executor

Codex · gpt-5.6 @ mediumcodex exec, one task per PR, never merges

Merge authority

Moeevery merge is yours; rollback stays one DNS re-point away

Locked decisions

Target

Classic Hydrogen v2026.4

React Router 7 + Vite, Storefront API pinned 2024-10 for parity

Hosting

Vercel, not Oxygen

vercelPreset() + custom server entry; adapter is spike v0.1-t2

Repo

~/babanuj-hydrogen

new sibling repo; production repo untouched

Cutover

Parallel run + parity gate

noindexed staging, automated audit, attribution rehearsal, then DNS

URLs

1:1 path parity

no Shopify/PostHog/Meta config changes needed at cutover

Checkout

checkout.babanuj.com

invariant — cart.checkoutUrl is never rewritten

Cutover gate

DNS does not move until every step is green, in order.

1URL-parity audit (full sitemap + redirects) 2Lighthouse: SEO 100, perf within 5 pts 3Cart smoke (checkout host asserted) 4Attribution rehearsal (real refunded order → PostHog) 5Runbook dry-run + rollback proven

Milestones

v0.1

Scaffold & platform risk spikes

1/5

Skeleton builds and deploys to Vercel; the three platform risks — deployment adapter, caching without workerd, edge rewrites — proven before any product code.

t1Scaffold Hydrogen skeleton repo + AGENTS.md invariantsMerged
t2Vercel deployment adapterSpikeApproved — awaiting merge
t3Caching without workerd Cache API — TTL matrixSpikePlanned
t4vercel.json rewrites/redirects + PostHog /ingest proofSpikePlanned
t5CI, husky guardrails, prettierPlanned

v0.2

Data layer

0/5

Shopify client, GraphQL documents, BabanujProduct adapter boundary, and seed-data fallback — callable from React Router loaders.

t1Domain data, types & pure helpers (BRANDS, CATEGORIES…)Planned
t2GraphQL documents & types, byte-identical, pinned 2024-10Planned
t3Storefront client port onto the TTL caching strategyPlanned
t4Adapter boundary + seed-data fallbackPlanned
t5/dev/data loader smoke route (dev-only)Planned

v0.3

Design system & layout chrome

0/4

Tailwind v4 tokens, self-hosted fonts, shared primitives, and the site shell so route milestones only assemble pages.

t1Tailwind v4 + globals.css + fonts into VitePlanned
t2Primitives: photo → Hydrogen Image, product-card, prose, iconsPlanned
t3Chrome in root.tsx: nav, cat-bar, footer, newsletter actionPlanned
t4Mobile menu portal, ErrorBoundary, 404, toasterPlanned

v0.4

Cart

0/4

Cookie cart end-to-end: single optimistic context, RR7 actions, /api/cart/add with PostHog stamping, drawer UI. Checkout-host invariant enforced by test.

t1Cart context — exactly one useOptimistic at the providerPlanned
t2Cart mutation actions (add / update / remove / checkout)Planned
t3/api/cart/add + posthog_distinct_id cart attributePlanned
t4Drawer, add-to-bag, cart pagePlanned

v0.5

Commerce & content routes

0/6

All 17 public pages as React Router routes, URL-identical to the old app.

t1Home — nine sections, deferred below-fold catalogsPlanned
t2Product page (/product/:handle) + PDP viewPlanned
t3Collections (/collections/:handle)Planned
t4Search page + /api/search typeaheadPlanned
t5Brand pages (/brand/:brandId)Planned
t6Content: $page catch-all, policies, reviews, honeytube, milaf-colaPlanned

v0.6

Customer accounts

0/4

Customer Account API OAuth behind the same URLs — Hydrogen's built-in client vs a port of the bespoke flow, decided by spike.

t1Hydrogen client vs bespoke OAuth portSpikePlanned
t2Auth routes (login/authorize/logout) + guardPlanned
t3Overview, orders, order detailPlanned
t4Profile & addresses mutationsPlanned

v0.7

Integrations & analytics

0/5

PostHog, Meta, GA4, Judge.me — behind the same public paths and env vars as production.

t1PostHog /ingest proxy + provider + identifySpikePlanned
t2orders/paid HMAC webhook → PostHog revenueSpikePlanned
t3Meta pixel + Conversions API with eventId dedupPlanned
t4GA4 + deferred third-party loaderPlanned
t5Judge.me widgets (re-init on soft nav)Planned

v0.8

SEO & parity

0/6

Everything Google sees — metadata, OG images, sitemap, redirects, structured data — plus the automated parity audit that gates cutover.

t1OG images via @vercel/og resource routesSpikePlanned
t2Metadata parity — seo.ts + meta exports + JSON-LDPlanned
t3Full redirect map generated into vercel.json (~24 rules)Planned
t4Sitemap + robots (host-keyed noindex on staging)Planned
t5URL-parity audit script (old sitemap vs new deploy)Planned
t6/api/revalidate disposition + TTL tuning (≤15 min staleness)Planned

v0.9

Parallel run & cutover

0/5

Noindexed staging next to production, automated + human gates, then a reversible DNS cutover with the old app as instant rollback.

t1Staging deploy with hard noindex + segregated analyticsPlanned
t2Automated gate: parity + Lighthouse + cart smokePlanned
t3Attribution rehearsal — real refunded order through PostHogPlanned
t4Cutover runbook + proven rollbackPlanned
t5Post-cutover cleanup after 2-week soakPlanned

Risk register

#	Risk	Severity	Mitigation
R1	No first-party Vercel adapter for classic Hydrogen — the glue is ours	Retired	Spike PASSED Jul 11: live Storefront SSR + streaming proven on a Vercel deployment. One residual: Hydrogen's POST Storefront proxy hits a Node duplex bug — tracked for v0.7 consent decision
R2	Losing tag-based revalidation → stale catalog	Medium	TTL matrix + ≤15 min staleness budget (v0.8-t6)
R3	SEO regression at cutover (canonicals, redirects, sitemap)	High	URL-parity script + gate; apex→www 308 explicitly re-verified
R4	Attribution chain breaks (PostHog revenue, Meta CAPI)	High	Byte-level HMAC test + full rehearsal with a real refunded order
R5	Hydrogen calver breaking changes quarterly	Medium	Pin exact versions; upgrades are explicit post-cutover tasks
R6	Shopify+Vercel's official direction is the new framework-agnostic Hydrogen (Next.js starter) — this port swims against that current	Medium	Acknowledged at sign-off; toolkit path documented as R1's fallback

Activity log

Jul 11
Vercel adapter spike PASSED — PR 002 approved. A Vercel deployment of the new project server-rendered a live product ("Zaitoune Baklava With Honey 500g") from the Storefront API 2024-10 and streamed the deferred chunk ~228ms later. R1 retired. One finding carried to v0.7: Hydrogen's built-in POST Storefront proxy fails on Node (duplex) — documented with remedies. Awaiting Moe's merge. PR #2
Jul 11
PR 001 merged by Moe — task 002 started. The Vercel adapter spike is running: Codex wires vercelPreset() + createHydrogenContext(), then the runner creates the new babanuj-hydrogen Vercel project (separate from production) and must prove live Storefront SSR + streaming on a preview URL. This is the R1 abort-criterion task.
Jul 11
PR 001 approved. Codex applied both review fixes (branch-naming scheme corrected to the hyphen form in AGENTS.md, node engines widened to ^22 || ^24); re-verified on origin, typecheck + build still green. Mergeable — waiting on Moe to squash-merge, then task 002 (Vercel adapter spike) begins. PR #1
Jul 11
PR 001 opened and reviewed — changes requested. Scaffold verified independently (build, typecheck, dev-server 200; Hydrogen 2026.4.4 + RR 7.16 pinned; no Oxygen config; commits authored Moe Ghashim + DCO). Two findings sent back to Codex: AGENTS.md documented a git-impossible branch scheme (slash under an existing branch ref → amended to hyphen), and node engines should allow ^24. PR #1
Jul 11
v0.1 breakdown approved; task 001 started. Codex produced 5 task files matching PLAN.md §9 with acceptance criteria intact — approved after independent verification (commits authored Moe Ghashim + DCO, protected paths untouched). Repo pushed to GitHub. Notes: executor model is gpt-5.6-terra (gpt-5.6/sol rejected on this ChatGPT plan; Decisions log updated), and Codex's sandbox can't write .git, so the runner performs commits/PRs with Codex-authored content verbatim.
Jul 11
Phase 2 handoff fired. Private repo moeghashim/babanuj-hydrogen created on GitHub; Codex (gpt-5.6 @ medium) invoked to generate the v0.1 task breakdown under dev/milestones/. It stops for review before any code.
Jul 11
Plan signed off by Moe. All defaults locked (bespoke shopifyFetch, API 2024-10, @vercel/og, CDN-TTL caching, Vercel-alias staging, 2-week soak). PLAN.md status → LOCKED.
Jul 11
Plan drafted. Codebase inventoried (17 pages, 8 handlers, 51 components), Hydrogen-on-Vercel research returned conditional GO, 44 tasks across 9 milestones written to PLAN.md. Awaiting Moe's sign-off — nothing handed to Codex yet.

PLAN.md is the contract: ~/babanuj-hydrogen/PLAN.md · Decisions-log rows win over everything downstream · This board is updated by the reviewer as PRs open, get reviewed, and merge.