Builder Builder

Setup

npm install
supabase start
npm run dev

Deployment environments

Where BB runs and which backing services it talks to.

| Deployment | Clerk instance | Supabase instance | | ----------------- | ---------------- | ----------------------- | | local dev | Clerk test | local supabase (docker) | | Vercel production | Clerk production | Supabase cloud project |

What lives where

Knowing what's stored in Clerk vs Supabase matters because npm run db:reset wipes Supabase but not Clerk.

| Lives in Clerk (survives db:reset) | Lives in Supabase (wiped by db:reset) | | ------------------------------------ | --------------------------------------- | | Users, orgs, roles, permissions | entities, entity_edits | | API keys (with all their claims) | builder_versions | | | variants, variant_edits | | | entity_references |

After a reset, you typically re-seed entities from a consumer repo. API keys keep working — re-seeding only repopulates Supabase.

Builder environments

Every entity carries an environment of development, staging, or production. Same database, different tables/rows. development rows are mutable; staging and production are immutable snapshots written by promotion.

| Environment | GET /api/builder/[id] returns | GET /api/builder/[id]/variants returns | | ------------- | ------------------------------- | ---------------------------------------- | | development | live editable entity | live editable variants | | staging | staging snapshot | staging snapshot variants | | production | production snapshot | production snapshot variants |

Promotion

The only path from development (mutable working copy) into staging or production (immutable snapshots) is through the Promote action in BB's UI. Promotion:

1. Runs validation on the entity and its references.
2. If validation passes, writes a new immutable row into the target environment's snapshot table.
3. If validation fails, the promote is rejected — nothing changes.

So builder_versions is, by construction, always free of validation errors. Consumers reading with environment: production never see broken data; consumers reading with environment: development may see in-flight errors and should expect to handle them.

Bulk writes that bypass the UI (like a seed script) land in entities only — they still need a UI promote afterwards to become visible to production-env consumers.

API key scoping

Each API key is minted in /settings with three properties:

| Property | What it controls | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Environment | Which dataset the key reads from: development, staging, or production. | | Profile | What the key can do. read keys can fetch; readWrite keys can also write variants. | | Allowed origins | Origin patterns (e.g. https://*.example.com) the key may be used from. Set this for browser keys; leave empty for server-to-server keys. The two modes are exclusive — a key with allowed origins requires an Origin header that matches, and a key without them rejects any request that has an Origin header. |

Keys are scoped to the org they were minted in and never see other orgs' data.

Clerk permissions

API key management is gated by org:api_keys:{create,read,update,delete}. These are custom organization permissions — Clerk doesn't ship them. In the Clerk dashboard:

1. Configure → Roles & Permissions → Permissions — define api_keys:create, api_keys:read, api_keys:update, api_keys:delete (Clerk prefixes them with org: automatically).
2. Edit the org Admin role — check all four, then save (defining a permission and granting it to a role are separate steps).

Members need to sign out/in for new role permissions to land in their session token. Setup is per-Clerk-instance, so repeat for Clerk test and Clerk production.

Scripts

• npm run verify — tests, check, format, lint.
• npm run test:integration:local — integration tests against local Supabase.
• npm run db:types:local — regenerate database.types.ts from local schema.
• npm run db:reset — wipe local Supabase, re-diff migrations, regenerate types. Does not touch Clerk.