Ratio-3.0

Appearance

Ratio-3.0The architecture, as a book

Read it front to back and you'll understand the whole system — what it is, how a request flows, how each piece works, and why it was built this way. Each chapter builds on the last.

Begin reading → Chapter 1
New contributor? Setup guide
Jump to the contents

📖 Part I · Foundations

What Ratio-3.0 is, the shape of the system, and how one platform serves many stores. Start here.

🚚 Part II · How the system works

Follow a request end-to-end — data flow, rendering & themes, commerce, and the control plane.

🏗️ Part III · The platform beneath

Where it runs — the edge, the origin, the CDN, the PWA it generates, and how it's observed.

🔬 Part IV · Under the hood

The line-level internals — the render engine, the theme pipeline, the edge, commerce, and auth.

How to read this book ​

This is written to be read in order — like a book, not a wiki. Each chapter assumes the ones before it, and by the end you'll have the whole system in your head. Use the ← Previous / Next chapter → links at the bottom of every page to turn the pages.

  • Picking up a ticket / new contributor? Start with For contributors → Setup to get running, then read the chapters your ticket touches. The Invariants & guardrails page is required first-week reading — it's the list of things you must not break.
  • New to Ratio-3.0? Start at Chapter 1 and read straight through Part II. That's the core — it gives you a complete working model of the system.
  • Going deep? Part IV opens every black box with code-traced, file-referenced internals. Read it after Parts I–III.
  • Just looking something up? The Appendices (data model, scripts, runbooks, decisions) are reference material — dip in as needed. Or use search (top-right).

Contents ​

For contributors (practical companion — how to work on it)

Part I · Foundations

  1. Overview — what Ratio-3.0 is and the three ideas it's built on
  2. The architecture — the services, the packages, the two trust tiers
  3. Multi-tenancy & routing — one shared system, many stores, kept apart

Part II · How the system works

  1. Request & data flow — a shopper's read path, a merchant's write path, and every flow between
  2. Rendering & themes — base ⊕ overrides, the two engines, the render cycle, blocks
  3. Commerce — the resolver + provider seams, cart, login, checkout, search
  4. Control plane & AI — Clerk + memberships, the audit trail, the AI assistant

Part III · The platform beneath

  1. Infrastructure — the edge, the ECS origin, the bundle CDN, environments
  2. PWA & assets — the installable app the origin synthesizes, and safe asset serving
  3. Observability — logs, metrics, and traces across edge and origin

Part IV · Under the hood (advanced, code-traced)

  1. Render internals — how a template, sections, blocks, and SEO are interpreted
  2. Render engine & isolate — the two engines, the worker pool, the tier gate
  3. Theme pipeline — the bundle format, publish, rebase, object store
  4. Edge internals — tenant resolve, serve-origin survival, breaker, headers
  5. Interactive commerce — the cookie protocol, checkout, KwikPass, account
  6. Commerce data & resolver — the binding seam, cache tags, the data-layer boundary
  7. Control-plane internals — the guard chain and the assistant's same-guards loop

Part V · Building & proving it

  1. Admin web (the SPA) — the React app merchants use: routing, state, the editor & customizer
  2. Testing & CI — the test pyramid, the end-to-end proofs, and the CI gate

Appendices

Keep it true

This book lives next to the code in apps/docs/. When you change how a subsystem works, update its chapter in the same PR — a book that lies is worse than no book.