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

Delegated to reviewerMoe's standing instruction Jul 11; local squash as Moe Ghashim + DCO; Moe retains override

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

5/5 ✓ done

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 adapterSpikeMerged
t3Caching without workerd Cache API — TTL matrixSpikeMerged
t4vercel.json rewrites/redirects + PostHog /ingest proofSpikeMerged
t5CI, husky guardrails, prettierMerged

v0.2

Data layer

4/5

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

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

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	Mitigated	TTL matrix proven on CDN (s-maxage 900 + SWR 86400); /api/revalidate path preserved; final tuning in v0.8-t6. Found & fixed: Hydrogen's tracking-cookie default made responses uncacheable
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
PR 009 merged — adapter boundary + seed fallback in. shopifyProductToBabanuj and the reverse bridge differ from production only in import paths (zero logic hunks); every env-fallback branch mapped 1:1; the no-network guarantee is enforced by a fetch-stubbed test. Task 005 (/dev/data health route — the milestone's live proof) started. PR #9
Jul 11
PR 008 merged — Storefront client ported, live-tested. All 16 legacy exports carried (cookie ownership moved to callers as designed); live integration tests against the real store passed: hidden-product filtering, menu/policies, and a real cart round-trip preserving the variant GID and the checkout.babanuj.com host. Reviewer independently confirmed cookie-attribute parity against production source. Task 004 (adapter boundary + seed fallback) started. PR #8
Jul 11
PR 007 merged — all GraphQL documents byte-identical. 22 template literals verified equal to production by an independent scanner; 19 exported documents pinned to a SHA-256 fingerprint recomputed from the old repo's own sources — any future query edit fails CI. Task 003 (the 647-line Storefront client, with an explicit cookie seam and env-gated live integration tests incl. the checkout-host assertion) started. PR #7
Jul 11
PR 006 merged — domain data ported with byte-parity. All seven pure modules verified byte-identical to production after quote normalization (data.ts 636 lines, redirects, shipping, contact, constants, type-guards); sole deviation is a one-line Next type substitution in utils.ts. Three-ID rule now enforced by unit tests in CI. Task 002 (GraphQL documents, byte-identical with a SHA-256 fingerprint test) started. PR #6
Jul 11
v0.2 breakdown approved — task 001 (domain data) started. Five task files on feat/v0.2-data-layer match PLAN §9 with criteria intact and the v0.1 learnings baked in (bespoke-client boundary, CACHE_NONE discipline). Task 001 ports the pure domain layer — brands, categories, vendor mappings, redirect data, seed products — value-for-value, with a unit test enforcing the brand/category three-ID rule.
Jul 11
🏁 v0.1 milestone closed and merged to main (d23b909). PR 005 (CI + guardrails) merged after its own CI ran green and the pre-push hook proved it blocks tracked .env files. DoD walked line by line: adapter ✓, caching ✓, edge routing ✓, test floor ✓, invariants preserved, open questions drained. v0.2 (data layer) breakdown now being drafted by Codex on feat/v0.2-data-layer. PR #5
Jul 11
Edge-routing spike passed — PR 004 merged (287f881); task 005 started. PostHog /ingest proxies live (real PostHog responses, SDK served first-party), redirects fire before RR7 routes, apex→www rule staged for cutover. Live-caught defect: Vercel ':path*' misses trailing slashes — /ingest/e/ 404'd until switched to '(.*)' captures. Task 005 (CI workflow, husky pre-push, Vitest + smoke floor) closes v0.1.
Jul 11
Merges delegated; PR 003 merged; task 004 started. Moe: "Merge and don't wait for me" — recorded in the Decisions log. PR 003 squash-merged locally as 95759d1 under Moe Ghashim <mohanadgh@gmail.com> (GitHub API squash stamps the wrong identity, so merges are local from now on). Task 004 is the last platform spike: PostHog /ingest reverse proxy + representative redirects (incl. apex→www rule) coexisting with React Router on Vercel.
Jul 11
Caching spike passed — PR 003 approved. CDN caching proven cookie-free on Vercel (MISS→HIT, identical timestamps). Real find: Hydrogen 2026.4 forwards Shopify tracking cookies onto every document by default, silently defeating CDN caching — disabled (matches production behavior; revisit pinned to v0.7). TTL matrix: catalog 15-min staleness + 24h SWR; cart private/no-store; /api/revalidate stays at its path as a secret-guarded no-op. Awaiting merge. PR #3
Jul 11
PR 002 merged (by Claude, on Moe's instruction) — task 003 started. Caching spike: named Cache-Control policies (catalog TTL/SWR within the ≤15-min staleness budget, cart private/no-store), a cache-demo route to prove MISS→HIT on Vercel's CDN, the TTL matrix mapping the old cache tags, and the /api/revalidate disposition decision.
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.