Dashboard overview

The control plane is where you operate a Papervine site: connect a repo, watch syncs, read analytics, manage domains, and change settings. It is a separate surface from the rendered docs — see architecture for how the two planes split.

The app host

The control plane lives on its own host: app.papervine.io (app.localhost:3000 in local development). Tenant docs render on subdomains or apex paths; the dashboard never shares their namespace.

Bare URLs, scoped by path

The dashboard is URL-scoped, with a familiar app.<your-domain>/{org}/{site} shape. A site’s home is the bare path app.papervine.io/:org/:site (in dev, app.localhost:3000/dev-org/starter). The active site is the URL, not a cookie — so dashboard URLs are shareable, bookmarkable, and work correctly across multiple tabs.

Behind the scenes the route files live at an invisible /app mount. middleware.ts Host-rewrites app.* bare /:org/:site to /app/:org/:site — the same rewrite trick tenant subdomains use to reach /sites/{slug}. It also bounces auth and stray /app hits on the apex over to the app host, so the session cookie is always set on app..

The org / site switcher

An organization can own several sites. The top-left switcher selects the active site that per-site pages (Overview, Analytics, Settings) scope to. It lists every site you can access plus a New site action.

Because the active site is encoded in the URL, switching sites simply navigates: the switcher preserves the current sub-page, so jumping from one site’s Analytics to another’s keeps you on Analytics.

Each site shows a small avatar — a colored gradient square with the site’s initial. The color is derived from the site’s slug, so every site gets its own hue and two sites that share a first letter still look distinct, making the list easy to scan at a glance.

Layout & design system

The control plane is built from a small set of shadcn/ui primitives in src/components/ui/ — buttons, inputs, selects, cards, tables, dialogs, dropdown menus, and a slide-in sheet. Each keeps shadcn’s structure but speaks the platform’s dark .db visual language rather than stock shadcn colors, so the whole dashboard reads as one surface and none of it leaks into the per-tenant docs renderer. Forms, the delete-confirmation dialog, and the site switcher are all assembled from these primitives.

Responsive shell

The dashboard adapts to the viewport:

• On desktop, the navigation rail is a fixed left sidebar, and Settings adds a second sidebar beside it.
• On mobile, the rail collapses behind a hamburger in a sticky top bar; tapping it slides the full navigation in as a drawer that closes when you pick a destination. The Settings sidebar becomes a horizontally swipeable strip of pills above the page. Content reflows to a single column with comfortable, screen-size-aware gutters.

The switcher and every page work the same way at both sizes — only the chrome rearranges.

Light & dark

The control plane has its own light and dark themes, separate from the per-tenant docs theme. A sun/moon toggle in the navigation footer flips between them, and your choice is remembered and applied before the page paints, so there’s no flash on reload.

The two themes are exact mirrors rather than two hand-built palettes: every translucent surface is drawn from a single “ink” channel that is white on the dark background and black on the light one, at the same opacity. So the dark theme is unchanged from before, and light is its reflection — the brand blue→violet accent and the status colors (green/red/amber) stay the same in both. Pop-over surfaces (menus, the delete-confirmation dialog, the mobile drawer) follow the theme too, even though they render outside the main shell — see gotchas.

The Overview home

The Overview is the per-site landing page — the default destination on entering a connected site. It is a consolidation surface: every panel is a window onto a system specified elsewhere (sync, the web editor, domains, routines), not a new capability. From top to bottom:

The Activity feed

The feed is the same deployment-backed history the control plane already renders; the Overview is its home. Each row shows:

• Actor — an avatar and name, or a system actor like Manual Update or Creating your site.
• Relative time — when the deploy ran.
• Status — Successful or failed. Failures expand to the persisted “Why it failed” reason and stack trace, so the cause is visible to the tenant rather than lost in serverless logs.
• Changes — a commit message and file counts (“11 files added, 27 files edited”). Rows expand for detail.

Live updates

A sync that lands while you are on the page appears without a reload — and resolves Building → Successful in place. Two mechanisms drive that, and the feed works on the slower one alone:

• Realtime delivers updates the instant a sync starts or finishes.
• Polling is the always-on fallback, so the feed stays live even when realtime is unconfigured or a socket drops.

The durable deployment row is the source of truth either way: a sync inserts it as building before the slow work and flips it to successful or failed at the end. Both mechanisms simply prompt the client to re-read it.

Realtime over the Pusher protocol

Updates arrive over a WebSocket using the Pusher protocol. Because serverless functions can’t hold a socket open, Papervine doesn’t run a socket server on its deploy target — instead it speaks a protocol that has both a server you can run yourself and a managed equivalent, swapped by environment (the same pattern as Postgres and object storage):

• Local uses a Pusher-compatible server you run yourself (Soketi) in docker-compose.
• Production uses hosted Pusher Channels — the same client and server SDKs; only env changes.

When a sync starts and finishes, the sync runner publishes a content-free ping on a per-site private channel; the browser, subscribed to that channel, reacts by re-running its normal authorized /activity fetch. No feed data ever transits the realtime host, and subscriptions are gated by an auth endpoint that reuses the same org-membership check as the page — a tenant can’t watch another’s channel.

An in-flight sync’s building pill counts up live (“Building 0:14”, with a pulsing dot), so a running sync reads as active rather than a static label. This is purely client-side: the row already carries its createdAt, so the feed ticks a 1s clock (only while something is building) and renders the elapsed time. The counter is scoped to live runs — an older building row is treated as a killed or orphaned run and drops the counter rather than ticking to infinity.

When something goes wrong

The dashboard is a client-navigated app: switching tabs fetches the next view in the background rather than reloading the page. If one of those fetches fails — a dropped connection, a momentary network blip — the affected view degrades to a recoverable card inside the dashboard, not a blank or broken page. The navigation rail and your session stay put; the content area shows a short explanation and a Try again button that re-loads just that view. For a transient hiccup, retrying simply works.