On this page
In short#
Onboarding an organization is a set of rows, not a branch in the source. Each customer-specific answer is carried as data and read by shared code through one door per seam; the short list that still needs an engineer is at the end.
The rule#
Tenant differences are data: the tenant's declared capabilities and configuration, read by shared logic. Product code never branches on a specific organization, slug or customer. Four less obvious shapes of the same bug are also guarded:
| Failure shape | Why it is the same bug |
|---|---|
| One customer's code book applied to every tenant's ingest | Writes one tenant's brand into another tenant's rows |
| A customer-pinned script shipped inside a production image | A per-customer branch that happens to live in a file |
| A process-wide flag carrying a hard-coded term list | Configuration that no row owns and no tenant can change |
| A connector schema defaulting a customer-shaped string | Every tenant leaving the field blank inherits one customer's answer |
Provisioning shape#
A blueprint registry holds the base shapes; an alias adds a domain layer to a base, so the HR, finance and warehouse workspaces are the dataset workspace plus one industry layer. The platform administrator's picker lists every provisionable shape, aliases included. Planning is a pure dry run with no reads or writes and produces the same summary as apply: one derivation. Apply accepts a branded key producible only from the administrator's input, so re-applying a resolved key cannot drop the domain layer, and writes one plugin-installation row per registry plugin, derived from the organization's domains. An explicit administrator choice outranks the shape rule in both directions and survives later reconciles. Steps: Provision a new organization.
Ingest that reads the customer's own vocabulary#
A stock-keeping-code book mapping codes to brands and categories is an installed, organization-scoped table under row-level security. The loader takes the caller's database handle and the decoder takes the book as an argument; the pure connector package holds no database client. With an empty book a code decodes to no brand and no category, never a guess. The reference book for seed and QA data has no tenant reader, and a static check refuses that symbol outside its home file.
Connector configuration#
Per-connector configuration is a JSON document on the credential row, validated by the connector's own schema. An audit refuses a top-level key in neither set. A field naming a customer-specific resource is required, not defaulted, so the server refuses a missing value; a rollup reading an empty configured id list writes nothing rather than something wrong.
| Key set | Holds | Effect |
|---|---|---|
| Source-key fields | Which external source the row points at | Compose the source key: two accounts per platform, one credential per source per brand |
| Operational keys | Sync toggles, intervals, look-back windows, page ids | Tune how the source is read |
The customer's own numbers and settings#
| Seam | Carried as | Read through |
|---|---|---|
| Dataset definition | Datasets and fields: role, temporality, expression, filters | The organization dataset resolver |
| Starter mapping templates | One per record dataset in a shipped pack | The dataset-pack template list |
| Navigation labels, order, hiding | One navigation-config row per organization and brand | The navigation-config resolver |
| Skin and brand ink | Theme rows and per-brand overrides | The theme scope resolver |
| White-label host | Organization domains verified by a DNS TXT record | The custom-domain locator |
| PDF footer brand | An override, honoured only with the white-label entitlement | The PDF footer resolver |
| Prompt wording | Prompt templates keyed by slot and optional industry | The prompt-slot resolver |
| Identity terms to mask | Masking terms and settings per organization | The masking-posture resolver |
Resolution order#
Each seam resolves from the most specific row outward and ends in a neutral default. The prompt default names no vertical, so an organization that sets nothing gets no industry framing rather than someone else's; a default that names a business shape is derived from the activated domains, and an unresolvable shape states its reason instead of becoming commerce.
Where it stops#
What still needs an engineer is below. Readiness per capability is on Project status.
| Need | Why it is code |
|---|---|
| New masking identity kind | Kinds are declared per domain; activating a domain inherits them |
| New industry id | Per-industry prompt defaults are a code map; wording per existing id is data |
| New connector type | A manifest, a driver and a sync registration |
| New connected app | A satellite manifest (client id, launch URL, scopes, plans) and an issuer client entry; see App family and identity hub |
| New blueprint or dataset pack | Repository content plus a registry-validity gate; not addable in the product |
| PDF footer text and link | Deployment-level; only the footer brand is per organization |
Decisions#
| Decision | Why | Enforced by |
|---|---|---|
| Every customer-specific answer is a row read by shared code | A special case for one customer eventually applies to another | A ratchet audit refusing named identities, pinned slugs, vendor ids and customer-shaped defaults |
| Provisioning writes the effective plugin set; a missing row is off | A request-time default changes every tenant when a manifest changes, with nobody deciding | Manifest validity audit, a matrix test per organization type, an idempotent reconcile test |
| Navigation, skins and labels are cosmetic; plugins, roles and page guards decide access | If hiding were the gate, a URL bypasses it and a label grants access | Page-guard and admin-route audits: every gated console page calls the tenant plugin guard |