Part 1 · 2 chapters · ~15 min

Tenancy and Region Models

Single-tenant, multi-tenant and region-sharded models with their isolation, cost and blast radius, data residency as a law that draws the map before the architecture, and the client's half: resolving the tenant once, routing to the home region, tenant-scoped caches and telemetry, visible country, and the tests that catch quiet failures.

3

Tenancy and region models

how countries share infrastructure
  1. Single-tenant per country: a full deployment each; total isolation; N of everything (on-calls, upgrades, certificates); cross-country features become distributed-systems problems. Right for a few countries with strict residency and large teams.
  2. Multi-tenant: one deployment, a tenant column on every row, row-level security making the scope mandatory; one of everything; a schema change everywhere at once; a bug is everyone's; residency cannot be met without a second deployment. Right for many small countries without residency constraints.
  3. Region-sharded: a multi-tenant deployment per region, a global control plane (platform identity, config, the release train) above; residency met per region; blast radius a region; R deployments, not N. The continent-spanning shape (the Cloud course for what regions cost).
  4. Data residency is law before architecture: storage and sometimes processing in-country; no replication out (including to a global warehouse without anonymisation); backups in; a CDN edge caching personal data abroad is a violation. Lawyers draw the map first.
  5. Cross-country users: two accounts are two tenants with a switcher, never merged. A country that moves region is a migration with a cutover and a client state for "this tenant moved: reconnect" (part 6).
TENANCY AND REGION MODELS
one deployment or many, one database or many, and where a country's data may live
swipe the figure sideways, or tap expand for full screen
1/6
single-tenant
Single-tenant: a deployment per country (its own services, database, CDN config, secrets). Isolation is total (a bug, an outage, a breach in one country stays there); cost is N of everything (N on-calls, N upgrades, N certificates); a cross-country feature (a user with accounts in two countries) is a distributed-systems problem. Right for a handful of countries with hard residency rules and large teams.
4

The client always knows where it is

the client's half of tenancy
  1. Resolution: the session after login (the Trust course part 1); before login, the URL, a stored preference, or a first-run choice defaulting from the locale, never from the IP alone (a traveller is still Nigerian). One source of truth in the shell.
  2. Routing: tenant to region to API base and CDN host from a map; the login endpoint is global and returns the home region; a user abroad is routed home; the country config (part 2) is fetched from the region. A hardcoded base URL is a bug that appears on the second region.
  3. Caching: every query key, IndexedDB name, localStorage key and service-worker cache includes the tenant; a logout or a switch clears or namespaces them. The failure: a switch from a Nigerian to a Kenyan account showing Nigerian balances from a cache keyed without the tenant.
  4. Telemetry: tenant and region on every event (the Architecture course part 3) so a country's regression is visible as such and residency rules for analytics apply per tenant; a country's on-call sees its own dashboards (part 7).
  5. Display: the country visible wherever confusion is possible (the switcher, the currency on every amount, the header for multi-account users, the regulatory footer); a traveller is told "you are using your Nigeria account", never silently served it.
  6. The checks: a lint forbidding base URL literals; a two-tenant render test asserting no cache key collides; an assertion that every event carries a tenant; a synthetic per region that logs in and reads a balance (the Big-company FE course part 8). Quiet failures need loud tests.
the exercise
Grep your client for base URL literals and for cache keys without a tenant. Each hit is a bug that appears on the second region; the count is how far you are from a platform.
THE CLIENT ALWAYS KNOWS WHERE IT IS
tenant resolution, routing, caching and display on the client side of a multi-region platform
swipe the figure sideways, or tap expand for full screen
1/6
resolution
Resolution: the session carries the tenant after login (the Trust course part 1); before login, the URL (ng.app.example, or /ng/), a stored preference, or a first-run choice with a sensible default from the locale (never from the IP alone: a traveller is still Nigerian). The resolved tenant is a single source of truth in the app shell; nothing reads it from anywhere else.