Appearance
Overview
Chapter 1. Start here. Everything later in the book builds on the three ideas in this chapter.
Ratio-3.0 is a multi-tenant storefront platform — "Shopify for India": cheaper, ultra-fast, AI-native. One shared, stateless system serves every merchant's storefront; a merchant is data keyed by tenant_id, not a deployment. It's a clean re-platform built for cost → performance → AI, in that priority order.
The big picture in one diagram
- Read path (shopper → HTML): the edge serves most requests straight from cache (~10ms); on a miss it asks the origin to render.
- Write path (merchant → live): admin UI → admin API → data, then it purges and warms the edge so the next shopper gets the new version.
Three ideas, stacked
Most of the system falls out of three ideas:
- Multi-tenant, shared host. No per-merchant servers. Every request carries a
tenant_id; all data (tenants,theme,pages,domains, …) is keyed by it in one Postgres. See Architecture. - One renderer, shielded by the edge. A Cloudflare Worker resolves
host → tenantand serves from cache; on a miss it proxies to a private origin that renders the page and returns cacheable HTML with surrogate cache tags. See Request & data flow. - A theme is
base ⊕ overrides. A merchant's theme = an immutable, versioned base library theme plus a small bundle of the files they changed. Improve the base once, rebase it into every store; a merchant's own edits survive because the merge is file-level. See Rendering & themes.
The stack at a glance
| Layer | Tech | Where |
|---|---|---|
| Edge | Cloudflare Worker + Workers KV (TENANTS) + Analytics Engine | apps/edge, packages/edge-core |
| Origin | Private Hono server on a Node container (ECS) | apps/origin |
| Rendering | LiquidJS, two engines (in-process + worker-thread isolate) | packages/builder-render, builder-core |
| Control plane | Hono admin API, Clerk authN + Postgres authZ | apps/admin-api |
| Admin UI | React + Vite + Clerk, Monaco code editor + visual customizer | apps/admin-web |
| Data | Postgres (Neon) for metadata; S3 + CloudFront for theme bundle bytes | packages/data-db, data-objects |
| Commerce | Pluggable resolver + provider seam; GoKwik as the first backend | builder-core/commerce, storefront-integrations |
| Monorepo | Bun workspaces (apps/*, packages/*), composition-root config (ADR-0001) | root |
The four services
apps/edge— the Cloudflare Worker. Host→tenant routing, edge cache, proxy to origin. Thin adapter over@ratio/edge-core(portable so a future Akamai adapter can reuse it).apps/origin— the single renderer. A private Hono server that resolves the tenant, loads the theme bundle, resolves page data, renders the sections + layout, and returns HTML. Refuses any request without the edge's shared-secret header.apps/admin-api— the write/control plane. Stores, domains, themes (draft → preview → publish → rollback), base propagation, commerce connect, the AI assistant. Clerk authN + PostgresmembershipsauthZ.apps/admin-web— the merchant/platform admin SPA. Two theme-editing surfaces (a Monaco code editor and a Shopify-style visual customizer), onboarding, settings, super-admin.
Where to go next
- The shape of the system → Architecture
- Follow a request end-to-end → Request & data flow
- Themes, blocks, the customizer, the two engines → Rendering & themes
- Data resolution + GoKwik + the provider seam → Commerce
- Cloudflare, ECS, the bundle CDN → Infrastructure
- Deploy pipeline + base propagation → Runbooks
- The why behind the big choices → Decisions (ADR)