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.