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.

Two domains, and why

Papervine serves from two separate registrable domains, and the separation is load-bearing:

	Domain	Serves
Platform	papervine.io	marketing apex, and the control plane on app.
Tenant	papervine.page	every customer’s docs site, at {slug}.papervine.page

The reason is cookie scope. A docs site renders customer-authored MDX, and for as long as that ran on a subdomain of the platform domain, it shared a registrable domain with the control plane’s cookies. The dashboard session is host-only on app., and even the benign “signed in” hint had to be httpOnly precisely because it reached tenant subdomains. Moving tenants to their own domain removes that exposure instead of mitigating it.

Two further consequences fall out of the split:

• No reserved labels on the tenant domain. Nothing of ours answers there, so docs, app, www and api are ordinary site slugs. Reserved labels still apply on the platform domain and on *.localhost in dev, where the platform and tenants share a suffix.
• The tenant host is configuration, not inference. tenantHostFor() returns the configured tenant domain rather than deriving one from the incoming request. Deriving would be wrong wherever a URL is minted while serving a platform request — the dashboard’s live links, the MCP endpoint, the widget’s citations — all of which run on app. and would otherwise emit the wrong domain.

Both domains come from NEXT_PUBLIC_PLATFORM_DOMAIN / NEXT_PUBLIC_TENANT_DOMAIN, so a deployment can differ. Leave them unset locally: dev shares .localhost for both, which means the split is not exercised in local development — it only becomes real in an environment with two actual domains.

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.