Hydrogen Architecture.

Overview

The Lund Studio Hydrogen scaffold is a React/Remix headless storefront deployed to Shopify Oxygen. It renders the 10,141 pages of the YGGDRASIL Liquid theme via the LivingPage shim (LUND-INV-194), with selected high-priority pages ported to native React components.

The scaffold was scaffolded, extracted, sharded, and shipped on April 20, 2026, the day the studio hit the Shopify 10,000-template limit with the Liquid theme YGGDRASIL v21.0.0. Rather than pay for Plus or delete pages, the studio architected around the cap by transitioning to a headless platform that has no cap of any kind.

File Structure

The canonical layout of the scaffold. Every file has a specific role.

lundstudio-hydrogen/
├── app/
│   ├── root.tsx                     # HTML shell + meta/link tags + global loader (menu)
│   ├── entry.server.tsx             # SSR entry + CSP nonce + bot detection
│   ├── components/
│   │   ├── Header.tsx              # DATA-DRIVEN nav (reads menu from rootData)
│   │   ├── Footer.tsx              # Brand footer with Four Marks sigil
│   │   ├── FourMarks.tsx           # Inline SVG brand mark component
│   │   └── LivingPage.tsx          # LUND-INV-194 · migration shim
│   ├── lib/
│   │   ├── content.ts              # LUND-INV-193 · sharded content loader
│   │   ├── menu.ts                 # Menu data layer (auto-menu)
│   │   └── session.ts              # Cookie session storage
│   ├── routes/
│   │   ├── _index.tsx              # Homepage (native React)
│   │   ├── pages.$handle.tsx       # Dynamic route — dispatches to LivingPage
│   │   ├── pages.the-curriculum.tsx # Native React port
│   │   ├── pages.register.tsx      # Native React port (masthead)
│   │   ├── pages.sitemap-auto.tsx  # Auto-generated full sitemap
│   │   └── sitemap[.]xml.tsx       # XML sitemap for search engines
│   └── styles/
│       ├── tokens.css              # LUND-INV-196 · Divinity Rule tokens
│       ├── base.css                # Base typography + layout
│       ├── home.css                # Homepage + Header/Footer styles
│       ├── curriculum.css          # Curriculum page styles
│       └── register.css            # Register page styles
├── data/
│   ├── content.json                # 10,141 pages metadata (2.9 MB lean manifest)
│   ├── manifest.json               # Compact slug+title+cat index
│   ├── shard-lookup.json           # slug → shard-number index
│   └── shards/
│       ├── shard-000.json          # 500 pages × body_html + styles
│       ├── shard-001.json
│       └── ... shard-020.json       # 21 shards × ~3.5 MB each
├── public/
│   └── four-marks.svg              # Browser tab favicon
├── server.ts                       # Oxygen worker entry (Cloudflare Workers)
├── package.json                    # Hydrogen + Remix + React deps
├── vite.config.ts                  # Hydrogen + Oxygen + Remix future flags
├── tsconfig.json                   # TypeScript strict mode
├── env.d.ts                        # Typed environment variables
├── .env.example                    # Shopify credentials template
├── extract.py                      # Build-time extractor (classifier embedded)
├── README.md                       # Quickstart guide
├── DECISION.md                     # Plus vs Headless decision doc
└── OPERATOR-PLAYBOOK.md            # Day-by-day rollout plan

Total: 55 files, 77 MB unpacked (6.3 MB packaged)

Data Layer

Three JSON files, one per concern. All generated by extract.py.

Routing

Remix file-based routing. Each file is a route handler.

/                         → app/routes/_index.tsx
/pages/*                  → app/routes/pages.$handle.tsx
/pages/the-curriculum     → app/routes/pages.the-curriculum.tsx  # native
/pages/register           → app/routes/pages.register.tsx         # native
/pages/sitemap-auto       → app/routes/pages.sitemap-auto.tsx    # auto index
/sitemap.xml              → app/routes/sitemap[.]xml.tsx          # SEO sitemap

All other /pages/{handle} paths resolve through pages.$handle.tsx,
which dispatches to the LivingPage shim for 10,138 of the 10,141 pages.
The three native routes (curriculum, register, homepage) are
first-class React implementations for the highest-traffic surfaces.

Sharding Topology

The architecture that enables 10,141+ pages from a 128 MB edge worker.

Content shards are alphabetically stable: page apache lives in shard-000.json because "a" alphabetically precedes all other first letters. Page zeus lives near the end of shard-020.json. Adding a new page shifts later slugs to potentially different shards at the next rebuild — this is acceptable because rebuilds are atomic.

Steady-state memory behavior under power-law access (most traffic on a small hot set of pages): approximately 10-15 MB of shard cache retained per worker instance. Under uniform distribution (rare): converges to ~75 MB total shard cache. Both well within the 128 MB ceiling.

Deployment

Oxygen + GitHub integration = continuous deployment with no configuration.

1. shopify auth login
2. shopify hydrogen link           # connects repo to Oxygen
3. git push origin main             # triggers Oxygen build
4. Oxygen builds Remix app
5. Oxygen deploys to Cloudflare Workers edge network
6. DNS: lundstudio.co → Oxygen worker

First-deploy time: ~5 minutes (cold cache)
Subsequent deploy time: ~45 seconds (warm cache)
Rollback time: instant (Oxygen maintains last 10 deploys)

Filings

Each of the eight Hydrogen-era inventions maps to a specific component of this scaffold.