Platform Architecture
The system split behind docs delivery, preview review, and domain orchestration.
DevDocs.dev is intentionally split into a reader-facing docs app and an operator-facing control plane. That separation keeps the public developer experience clean while still supporting heavier workflow automation behind the scenes.
Runtime split
Docs App
Public content, preview review surfaces, and the branded reading experience.
Control Plane
Provisioning, preview lifecycle visibility, domain ownership, and control-plane actions.
Control-plane assumptions
- the control plane runs at
admin.devdocs.ai - customer docs sites default to readable subdomains on
<tenant>.devdocs.dev - Statebacked owns long-running deployment and domain workflow state
- Vercel provides the docs artifacts and preview surfaces
- Cloudflare owns the public-facing DNS and routing layer
Why the docs shell matters architecturally
The docs frontend is not just a marketing wrapper. It is the primary review surface for previews, onboarding, and trust. If that surface feels shallow or broken, the product feels shallow or broken even when the backend systems are correct.
Reader trust is part of system design
A clean page tree, stable sticky navigation, and stronger content hierarchy are not cosmetic extras. They are part of how reviewers and customers decide whether the product feels dependable.
Render strategy
| Concern | Strategy |
|---|---|
| Public docs pages | Static or pre-rendered whenever possible |
| Preview diagnostics | Lightweight dynamic pages that stay safe in previews |
| Protected workflows | Pushed into the control plane rather than the public docs surface |
Preview-safe posture
Docs expectations
- preview docs should remain
noindex - review routes such as
/preview-statusshould stay reachable - review tooling should work with Vercel automation bypass when protection is enabled
Control-plane expectations
- control-plane pages remain protected
- preview-safe mode keeps heavier managed work disabled
- auth boundaries stay obvious during review
Why the docs experience carries the product
DevDocs.dev has to make sophisticated platform work feel understandable from the first screen:
- OpenAPI references should become browsable, testable, and SDK-ready
- interactive walkthroughs should combine explanation, code, and live context
- CLI and sandbox flows should feel native to the documentation experience
- pages should be structured well enough for both human readers and AI retrieval
The work for us is to make that public product layer feel compelling, trustworthy, and operationally real.