Platform Architecture
The system split behind docs delivery, preview review, and domain orchestration.
DevDocs Portal is intentionally split into a reader-facing docs app and an operator-facing control plane. That separation helps us keep the docs shell clean while still supporting heavier workflow automation behind the scenes.
Runtime split
Docs App
Public content, preview review surfaces, and the branded reading experience.
Admin Portal
Provisioning, preview lifecycle visibility, domain ownership, and control-plane actions.
Control-plane assumptions
- the portal 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 admin portal 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
Portal expectations
- control-plane pages remain protected
- preview-safe mode keeps heavier managed work disabled
- auth boundaries stay obvious during review
Why Fumadocs stays the right UI base
Fumadocs already gives us the parts we want for content delivery:
- MDX support with search-friendly structure
- a strong docs layout with sidebar and TOC primitives
- composable page-tree rules for multi-section docs
- enough theme flexibility to land closer to the DevDocs brand
The work for us is to make the product layer around that foundation compelling and operationally trustworthy.