Registry

A registry is a hosted, standalone deployment of handoff-app, the same Next.js application a workspace runs locally, just started with DATABASE_URL set. It contains no client-specific data at deploy time: everything a stakeholder or agent sees arrived later, via a workspace's handoff-app push:all (or a selective push), and lives in Postgres. See Model for why this shape replaced the older per-client materialization approach.

Today one registry serves one workspace (one figma_project_id), "multi-tenant" in the sense that many client registries run off the same handoff-app codebase, not in the sense of multiple tenants sharing one database. Multi-tenancy within a single registry is deferred (see ADR-001).

What a registry does

• Stores everything a workspace pushes, components, patterns, pages, tokens, theme, navigation, icons, logos, fonts, and project config, as rows in Postgres, most of it as singleton config rows rather than per-project files.
• Serves it back out over three surfaces: the stakeholder-facing UI (see Stakeholder-facing UI routes), the REST API, and MCP, the same three-surfaces principle that runs through the whole data model.
• Authenticates two different audiences with two different mechanisms: a NextAuth session for the browser UI, and a bearer token (sync secret or OAuth JWT) for the CLI and MCP clients, see Auth.
• Migrates itself. npm run build:registry applies any pending, journaled database migrations as a build step, before next build runs, no separate migration step in a deploy pipeline. See First-admin setup for what happens right after that.

Where to go next

• Model: the registry-as-a-service architecture (ADR-001) and the DataProvider pattern that lets the same codebase run as a workspace or a registry.
• Deploy: standing one up locally with Docker, or in production on Vercel.
• Environment variables: every registry-side and workspace-side variable, required and optional.
• First-admin setup: the /setup flow (or the non-interactive bootstrap script) that creates the first admin account.
• Singleton config rows: how config, theme, appearance, navigation, and the DTCG token manifest are each stored as one upserted row per registry.
• Auth: NextAuth session auth for the registry's own UI: providers, roles, invites.
• Stakeholder-facing UI routes: the pages a registry serves for browsing the system, grouped by audience.