Architecture

Papervine is docs-as-code: the source of truth is MDX + a docs.json in your Git repo, never the platform. The deployed app holds no tenant content at build time — content is fetched and rendered on demand, with aggressive caching, so a new deploy never requires rebuilding every tenant’s site. Everything below follows from that: a stateless renderer that resolves a tenant per request, and a control plane that syncs Git into a content store for the renderer to read.

            Git repo (MDX + docs.json)
                     │ push webhook
                     ▼
   Dashboard ──▶ Control Plane ──▶ Content Store ──▶ Render Plane
  (settings,      (tenant mgmt,     (Postgres,        (multi-tenant
   members,        git sync,         object store,     Next.js app:
   analytics)      domains)          cache)            resolve → render)

Two deployable planes

Papervine is one Next.js codebase that exposes two surfaces. They can split into separate deployments later for scaling, but v1 is a single app with different route groups.

The two planes are deliberately themed apart and must never leak into each other:

• The docs renderer is light-first and themed per tenant from docs.json (src/lib/theme.ts, globals.css) — see config.
• The control plane shares one dark, luminous design language codified in src/styles/platform.css (scoped under .db) and applied via <PlatformShell>. Its UI primitives are shadcn/ui mapped onto the .db palette. The neutral tokens resolve only inside the .db scope, so they cannot bleed into the renderer.

Tenant resolution

Next.js middleware (src/middleware.ts) inspects the Host header and rewrites internally so the right tenant renders — without touching the database at the edge. Edge middleware classifies by host suffix only (isPlatformHost / isAppHost); anything that needs the DB happens downstream in a Node-runtime route.

resolveTenantSlug (src/lib/tenant-host.ts) reads the host and picks one of two serving modes:

The apex, www, and reserved labels resolve to the platform landing and control plane — never a tenant. The isAppHost check routes the app. host to the control plane.

Keeping config and pages on the same source

Because content is fetched per request, the renderer scopes the active content source with request-scoped storage. A single requestContentSource() (src/lib/request-source.ts) resolves the tenant source from the x-papervine-site header (stamped by middleware for both subdomain rewrites and apex path mode), or from the host. The root layout and the page both read config inside that scope, so the sidebar (built from docs.json) and the page body always come from the same tenant — not the platform’s default content.

The API routes need the same care: middleware does not rewrite /api/*, so /api/search and /api/assistant resolve their source explicitly via requestContentSource(site) and run their whole body (including streaming tool calls) inside that scope. In path mode the request hits the apex with no tenant in the host, so the client passes the active slug explicitly (?site= / body site). See search and the AI assistant.

Custom domains (BYO docs.example.com)

There are two independent domain systems. Don’t conflate them.

Owners connect or remove a domain and choose root vs /docs hosting (customDomainSubpath) at Settings → Domain setup. In /docs mode the route owns only the /docs/* subtree, so the customer keeps their apex for other purposes. A custom-domain request never goes through /sites — the slug isn’t known at the edge — so middleware forwards the raw host (x-papervine-host) and rewrites to a dedicated /custom-domain/[[...path]] route (Node runtime, has DB) that resolves the site or returns notFound().

Where to go next

• Tech stack — the chosen building blocks and the monorepo layout.
• Content pipeline — how a Git push becomes compiled bundles.
• Renderer internals — the hybrid MDX pipeline that never 500s.
• Introduction — the project at a glance.