Multi-tenant platform

Prood runs as a white-label, multi-tenant commerce platform: one deployment serves many merchant stores. Each store is a Better Auth organization, and all commerce data is isolated per organization by Postgres row-level security (RLS).

Domain architectureCopy Anchor Link

NEXT_PUBLIC_PLATFORM_DOMAIN=prood.app applies only to merchant storefront subdomains ({slug}.prood.app), not to platform services on prood.com.

Tenant modelCopy Anchor Link

Storefront host resolutionCopy Anchor Link

The storefront resolves the active tenant in apps/storefront/lib/tenant.ts:

1. Custom domain — lookup verified row in tenant_domain table
2. Subdomain — {slug}.{NEXT_PUBLIC_PLATFORM_DOMAIN} → organization.slug Unmatched hosts redirect to the marketing site. Locally, the seeded demo store is served at prood-demo.localhost:3000.

Per-tenant cachingCopy Anchor Link

Catalog reads are cached per tenant with tags like products-{orgId}, categories-{orgId}, store-{orgId}. Cache never crosses tenant boundaries.

Row-level securityCopy Anchor Link

RLS is defined in the Drizzle schema and shipped as versioned migrations in packages/platform/drizzle:

1. 0000_app_role.sql creates the prood_app role (NOLOGIN NOBYPASSRLS), lets the connecting role SET ROLE to it, and grants it SELECT, INSERT, UPDATE, DELETE on the public schema, including default privileges for tables created by later migrations.
2. Every tenant table uses the helpers in packages/platform/src/database/drizzle/schema/tenant.ts: a NOT NULL organization_id column that defaults to app.current_org_id, and a tenant_isolation pgPolicy for prood_app (USING and WITH CHECK on organization_id). Drizzle enables RLS on every table with a policy.

The app connects with a role that has BYPASSRLS (on Neon, the database owner), so RLS is enforced by switching roles, not with FORCE ROW LEVEL SECURITY. Every commerce query runs inside withTenant(orgId):

// packages/platform/src/database/drizzle/client.ts
export async function withTenant<T>(orgId: string, fn: () => Promise<T>): Promise<T> {
  return getBaseDb().transaction(async (tx) => {
    await tx.execute(sql`select set_config('app.current_org_id', ${orgId}, true)`)
    await tx.execute(sql`set local role prood_app`)
    return tenantStore.run({ db: tx, organizationId: orgId }, fn)
  })
}

Both settings are transaction-local, so a pooled connection returns to the connecting role afterwards. Queries also add tenantCondition() (organization_id = <active org>) as defense in depth.

Paths that must read across tenants stay outside withTenant() and run as the connecting role: migrations and the seed, host → tenant resolution (organization, tenant_domain), Better Auth, and linking a new account to its guest customers in every store.

Unique keys that repeat across stores include organization_id: product, category and brand slugs, order numbers, coupon codes, customer ↔ auth-user links, and the store_info primary key.

Verifying isolationCopy Anchor Link

Run the same statements withTenant() runs, against a database with two organizations:

BEGIN;
SELECT set_config('app.current_org_id', '<org A id>', true);
SET LOCAL ROLE prood_app;
SELECT id, organization_id FROM products;                      -- only A's rows
SELECT id FROM products WHERE organization_id = '<org B id>';  -- 0 rows
INSERT INTO products (id, organization_id, name, slug)
VALUES ('x', '<org B id>', '{}', 'x');
-- ERROR: new row violates row-level security policy for table "products"
ROLLBACK;

-- prood_app without a tenant sees nothing
BEGIN;
SET LOCAL ROLE prood_app;
SELECT count(*) FROM products;  -- 0
ROLLBACK;

packages/platform/src/__tests__/platform.drizzle.test.ts covers the same cases.

Onboarding a new merchantCopy Anchor Link

1. Register in the dashboard → creates a user + first organization (the store)
2. The org ID becomes the tenant key for all commerce data
3. Add a domain in Dashboard → Domains (subdomain is automatic; custom domains use Vercel SDK + DNS verification)
4. The storefront at that host resolves to the org and shows the merchant's catalog

See Merchant onboarding guide for the full walkthrough.

Per-tenant integrationsCopy Anchor Link

Payment credentials configured in the dashboard (integration_config table) flow into the provider factory at runtime:

Provider registry field keys in apps/dashboard/lib/providers.ts match provider constructor params, so stored config maps directly.

Encryption at restCopy Anchor Link

integration_config.config values are encrypted using INTEGRATION_ENCRYPTION_KEY. The key is required. Values without the enc:v1: prefix are treated as plaintext during development or migration cleanup.

Storage namespacingCopy Anchor Link

File uploads use tenant-prefixed keys:

uploadForTenant(orgId, input)       // key: org/<orgId>/...
tenantStorageDirectory(orgId, ...)  // directory prefix

Merchants cannot collide with each other's assets. Every object is public through the media Worker, and uploaded filenames get a short random suffix.

Package security postureCopy Anchor Link

Environment variablesCopy Anchor Link

Adding new tenant tablesCopy Anchor Link

When adding a new tenant-owned table:

1. Define it in packages/platform/src/database/drizzle/schema/ with organizationId: organizationId() and tenantIsolation() in the table's extra config (see tenant.ts), plus an index on organization_id or a unique key that starts with it
2. If a natural key repeats across tenants, make it unique per tenant (unique().on(t.organizationId, t.slug)) or include organization_id in the primary key (see store_info)
3. Run pnpm db:generate and commit the generated migration, then pnpm db:migrate
4. Make sure its queries run inside withTenant() and add tenantCondition()

Custom domains (two products)Copy Anchor Link

Merchants can have two different kinds of custom domain:

Store custom domain (partially implemented)Copy Anchor Link

• Configured in Dashboard → Domains
• Stored in tenant_domain, verified via DNS
• Attached to the storefront Vercel project (STOREFRONT_VERCEL_PROJECT_ID)
• Free plan includes one verified store custom domain (maxCustomDomains in billing)

Admin white-label domain (Phase 3 — not implemented)Copy Anchor Link

Similar to DatoCMS dashboard.datocms.com vs admin.casalume.example:

• Default admin URL for all merchants: dashboard.prood.com
• Scale / Agency (planned): optional admin.casalume.example with DNS verification
• Routes to apps/dashboard, not the storefront
• Requires a separate Vercel project attachment, dashboard host → org lookup, and Better Auth trusted origins per custom admin host
• Planned billing gate: customAdminDomain entitlement on Scale and Agency only

Store and admin custom domains are independent — a merchant might use shop.example.com for customers and cms.example.com for their team.

Related pagesCopy Anchor Link