Database Flow
BrightWeb uses a modular database ownership model. Shared migrations live under module folders, client stacks declare enabled modules, and the repo can plan or materialize an installable Supabase workdir from that resolved stack.
Module migrations
supabase/modules/coreowns shared auth/profile, events, preferences, notification state, and rate-limit foundations.supabase/modules/adminowns RBAC, role assignment, role audit, and governance helpers.supabase/modules/crmowns organizations, CRM contacts, membership, invitations, and CRM-specific policies and helpers.supabase/modules/projectsowns projects, tasks, milestones, links, activity, and project-specific access rules.
Client stack files
In workspace mode, a new platform app gets
supabase/clients/<slug>/stack.jsonplus a client-only migrations folder. The stack records enabled modules, client migration path, and notes about the resolved database stack.
Materialization
Materialization writes a generated Supabase workdir under supabase/.generated/<client-slug>. That workdir includes ordered migrations merged from Core, enabled modules, and client-only deltas, plus a generated config.toml and a manifest.json mapping the source of each migration.
Use the existing commands
pnpm db:plan begreen
pnpm db:materialize begreen
pnpm db:new core profile_notification_cursor
pnpm db:new admin role_change_guard
pnpm db:new crm organization_invite_expiry
pnpm db:new projects task_due_date_index
pnpm db:new client:begreen bespoke_reporting_table
Greenfield install vs forward-only upgrades
| Client type | Current rule |
|---|---|
| New client | Provision from the BrightWeb module structure: apply Core, then enabled shared modules in dependency order, then client-only migrations if needed. |
| Existing client like BeGreen | Do not rewrite old history. Treat the live schema as authoritative and apply new BrightWeb-owned changes as forward migrations only. |
Practical flow
- Choose the client and confirm its enabled modules.
- Resolve apply order from the module registry and stack file.
- Plan or materialize the generated Supabase workdir.
- Apply new changes as forward migrations only.
- Keep client-only migrations rare and isolated.
Related docs
- Dependency Resolution
- Database Module Migration Structure
- Database Migration Authoring Workflow
- Database Migration Safety Policy
Repo sources
supabase/README.mddocs/architecture/database-module-migration-structure.mddocs/architecture/database-migration-authoring-workflow.mddocs/architecture/database-migration-safety-policy.mdscripts/_db-modules.mjs
Repo source
docs/architecture/database-flow.mdThis page is rendered directly from the root docs folder. Edit the markdown there, not inside the app.
PreviousDependency ResolutionBrightWeb resolves module order from the registry, not from ad hoc assumptions. The current chain is linear: **Core** first, then **Admin**, then **CRM**, then **Projects**.NextUI vs Domain ModulesThe current BrightWeb model separates shared platform ownership from client app ownership. Shared modules own schema, policies, contracts, and domain and server logic. Client apps own the actual product UI built on top of those shared layers.