Appearance
Where things live
A lookup table keyed the way you ask when you get a ticket: "where's the cart? the theme editor? auth?" Find your area, open the entry file, read the chapter for context.
| I'm working on… | Package / app · directory | Entry file(s) | Chapter(s) |
|---|---|---|---|
| The edge (routing, cache, proxy) | apps/edge + packages/edge-core | apps/edge/src/worker.ts | 8, 14 |
| The renderer (the origin) | apps/origin | src/index.ts, src/handlers/* | 4, 5, 11 |
| The page render specifically | apps/origin/src/handlers | storefront.ts | 5, 11 |
| Themes (base ⊕ overrides, publish) | packages/builder-core/src/theme | theme-store.ts, theme-compose.ts, theme-render.ts | 5, 13 |
| The Liquid engines / isolate | packages/builder-render | engine.ts, isolate.ts, worker.mjs | 12 |
| Section registry / tiers / islands | packages/builder-registry | registry.ts, islands.ts | 12 |
| Commerce read-data / resolver | packages/builder-core/src/commerce | resolve.ts, resolve-shopkit.ts | 6, 16 |
| The cart | apps/origin/src/handlers + packages/builder-core/src/storefront | cart.ts, storefront/cart.ts | 6, 15 |
| Checkout / login / side-cart | packages/storefront-integrations | checkout/, kwikpass/, side-cart/ | 6, 15 |
| The account page | apps/origin/src/handlers + packages/builder-core/src/commerce | account.ts, account-data.ts | 15 |
| Search | apps/origin/src/handlers + packages/builder-core/src/commerce | search.ts, search-data.ts | 6 |
| PWA (manifest / icons / SW) | packages/builder-core/src/theme | manifest.ts, icon.ts, service-worker.ts | 9 |
| Assets serving | apps/origin/src/handlers | assets.ts | 9 |
| SEO | packages/seo | head.ts, structured-data.ts, sitemap.ts | 11 |
| Auth (authN + authZ) | apps/admin-api/src/middleware | auth.ts | 7, 17 |
| The admin API (control plane) | apps/admin-api | src/app.ts, src/routes/* | 7, 17 |
| Domains / provisioning | apps/admin-api/src/{routes,services}/domains.ts + packages/data-provisioning | routes/domains.ts, services/domains.ts | 8 |
| The AI assistant | apps/admin-api/src/services | assistant.ts | 7, 17 |
| The admin SPA (frontend) | apps/admin-web | src/App.tsx, src/features/* | 18 |
| The theme editor / customizer | apps/admin-web/src/features/theme | theme-editor.tsx, theme-customizer.tsx | 18 |
| The data model (Postgres) | db/migrations + packages/data-repo | 0001_init.sql, forTenant(...) | A |
| The object store (S3/MinIO) | packages/data-objects | s3.ts, cdn-read.ts | 13 |
| Observability (logs/metrics/traces) | packages/observability* | observability-edge, observability | 10 |
| Deploy / CI | .github/workflows + infra/aws/bundle-cdn | ci.yml | C |
| Ops scripts | scripts/ | onboard.ts, migrate.ts, republish-base.ts | B |
The composition-root rule
Only apps/*/src/config.ts read process.env. Every package takes its config injected — so a package never reaches for a global, which is why the same builder-core runs in the origin, the admin-api, and (trusted parts) the edge. If you need an env var in a package, thread it through, don't process.env it.