Vord

Architecture Decision Record

0012. The tenant and realm model

Context

The constitution makes the tenant the shard and isolation boundary (ADR-0001 rule 3) — which makes tenancy a Vord concept, owned here. Vord consumes only Wyrd's mechanical hooks for it — namespace partitioning (Wyrd ADR-0020) and subtree placement (Wyrd ADR-0018 §2) — and not Wyrd's tenancy semantics: Wyrd's own multi-tenancy model (Wyrd ADR-0022) is the sibling model for Wyrd's storage product, referenced here as prior art, never a dependency. Depending on a Wyrd tenancy model for identity would push identity semantics down into Wyrd — the god-component move rule 4 forbids. What Vord must define is the identity model itself: Vord serves two products from one platform — workforce SSO (an organisation's employee directory; the Entra/Okta shape) and CIAM (an app's end-user pool; the Auth0 shape) — and must say whether those are one model or two, where isolation is enforced in Vord's own planes, and how the model holds at the stated scale (500K+ principals per workforce tenant; millions per CIAM realm). Wyrd ADR-0022 left one question explicitly open that Vord now owns: whether a very large tenant warrants a dedicated namespace shard.

Decision

  1. Tenant = a Vord-owned concept: a Wyrd namespace partition (consuming Wyrd ADR-0020) bound to an identity domain (one or more OIDC realms) and a policy bundle. The model is Vord's; only the namespace and placement mechanics are Wyrd's. A realm is an issuer boundary within a tenant — its own discovery document, keys (ADR-0023), clients, and authentication policy. A workforce tenant is typically one or few realms (the org and its environments); a CIAM tenant carries realms per app or per end-user population. The realm is also the principal-pool boundary: identifier uniqueness is (realm, identifier) (ADR-0011), so realm-per-population means separate, mutually-invisible user pools, and a tenant that wants one pool across several apps models them as clients of one realm — the sharing is chosen, never accidental.

  2. Workforce and CIAM are realm types, not separate mechanisms. The difference is policy carried in the realm — self-service registration, social login (ADR-0019), progressive profiling and consent for CIAM; IdP-federated, SCIM-provisioned, admin-governed for workforce — over the one principal model (ADR-0011) and the one issuance/verification/authorization stack. Two products, one platform.

  3. The four isolation boundaries land in Vord's planes. The same four-boundary pattern Wyrd applies to its storage tenants (Wyrd ADR-0022), here enforced in Vord's own admission plane (Modgud, ADR-0009) and never below: namespace (per-tenant partition of the directory on Wyrd's namespace store, Wyrd ADR-0020 — cross-tenant traversal impossible by construction); cryptographic (per-tenant key separation, ADR-0023, and Wyrd's per-tenant envelope encryption for directory data at rest); capacity (per-tenant quotas — principals, clients, request volume — checked at admission); performance (per-tenant rate limits and fair scheduling, so one tenant cannot monopolise issuance throughput).

  4. Per-tenant data residency via placement-over-subtree. "Pin this tenant's directory and issuance core to eu-west" is one placement policy over the tenant's namespace subtree (Wyrd ADR-0018 §2), and home-zone authority follows for everything beneath it. Edge verification remains global regardless, because it is core-independent (ADR-0010) — residency constrains where the core lives, not where tokens can be checked. This is the deployment expression of the constitution.

  5. Very large tenants shard, they do not fork. A tenant at the top of the scale range (500K+, or a CIAM realm in the millions) may be assigned a dedicated namespace shard for op-rate headroom — this is a placement and sharding decision (scale on per-tenant metadata-op-rate, Wyrd ADR-0018 §4), not a second tenancy model. Multi-tenancy stays logical (shared infrastructure) by default; dedicated shards or dedicated hardware are an operational tier layered on, settling for Vord — the question Wyrd ADR-0022 left open for its storage tenants — in favour of one model with a sharding knob. This is the answer the constitution's rule 3 already points to: the tenant is the shard, so sharding a big tenant is the model working, not bending.

  6. The tenant is the write-rate shard boundary, and write rate is the binding constraint. Verification scales off the core (ADR-0010); the ceiling that remains is the issuance / registration / grant write path, strongly-consistent by necessity — issuance hits the Wyrd core, a permission grant hits the Forseti store (ADR-0026). At CIAM scale the binding constraint is login / registration write rate, not verification throughput. The honest claim is therefore narrower than the headline: Vord beats a single-store identity system at scale to the extent that the per-tenant-sharded Wyrd metadata tier (Wyrd ADR-0018 §4) and a sharded Forseti store out-write one database — real, but the part to prove under a login-storm, not the part the verification story may distract from. The tenant shard is the unit that distributes that write load.

Consequences

  • One platform serves workforce and customer identity without a schema or stack fork; the competitive surface against Entra/Okta and Auth0 is realm policy, not parallel products.
  • No cross-tenant strongly-consistent read sits on any hot path (rule 3); admin conveniences that would need one ("all sessions across all tenants") are served from projections or refused, per ADR-0001.
  • Residency is a one-line placement policy per tenant, and it never costs edge verification latency — the constitution's payoff made concrete.
  • The dedicated-shard tier for the largest tenants is reserved as an operational option; it is validated at the multi-tenant milestone (M4) and the hyperscale milestone (M8) of the implementation arc, where the 500K/millions targets are exercised against the real metadata tier.
  • The write path is a first-class scaling dimension, not an afterthought: issuance and grant writes shard per-tenant across two strongly-consistent domains (ADR-0026), and proving the distributed write path under login-storm load is a definition-of-done at M4 and M8 — the claim that makes the CIAM number honest.
  • Cross-tenant sharing (a relationship or grant spanning two tenants — e.g. B2B guest access) was left [OPEN] here and is settled by ADR-0046: there is no cross-tenant relationship at all — an external collaborator becomes a local guest principal with an informational home reference, so every grant, token, and lifecycle decision stays tenant-local and rule 3 is preserved by the data model.