4 / 8 Read-Heavy Web Systems

Docs At The Edge

Design the serving and publishing system for a global developer documentation site.

Requirements

Functional

  • Serve versioned docs: every product has many released versions, and old versions stay readable forever.
  • Full-text search scoped to one product version, ranked by relevance.
  • Editors publish from a headless CMS. A publish may touch one page or an entire release of thousands of pages.
  • A published change must be visible worldwide within 60 seconds.

Non-functional

  • p95 time to first byte under 100 ms for readers on every continent.
  • Reads dominate: roughly 99.9% of requests are reads.
  • A release must never leave the site serving a half-updated version (no nav linking to a page that 404s).
  • Search may degrade before page reads do.

Scale

  • 2.5M daily readers, about 30M page views per day.
  • Peak 12,000 HTTP requests per second at the edge, of which roughly 3,000 per second are document requests.
  • 720k live pages (40 products x ~15 versions x ~1,200 pages), each about 60 KB of rendered HTML plus a 25 KB JSON payload for the client-side router.
  • Peak 250 search queries per second.
  • 300 publish events per day. The largest single release rewrites 5,000 pages at once.
  • Corpus grows about 25% per year, and no version is ever deleted.

Out of scope

Authentication for private docs, the CMS editing experience itself, billing, and the analytics pipeline.