Cosmology for multi-tenant: universe, system, environment

The conversation about multi-tenant almost always starts in the wrong place. Somebody draws a box on the whiteboard, labels it "Tenant," and nests a few smaller boxes inside it labelled "Sub-tenant." The room nods. The schema gets a parent_tenant_id column. The auth library learns to walk the chain. Six months later somebody asks, "wait, which level does the BAA apply to?" and the answer is a long silence followed by an architecture review nobody wanted to be in.

I've been in that review enough times to be sure the problem is upstream of the schema. The flat parent/child framing of "tenant" and "sub-tenant" is the wrong shape for what real multi-tenant systems do. It hides the fact that multi-tenancy is multi-scale. There isn't one nesting relationship, there are several, each with different rules, different boundaries, different blast radii. The vocabulary forces you to collapse them all into one parent/child line, and then you spend the rest of the project untangling things you should never have braided.

The metaphor I keep reaching for is cosmological. Universe, galaxy, solar system, planet, operating environment. Not because astronomy is technically illuminating (it isn't) but because cosmology is a layered hierarchy where each layer has a different kind of containment. Galaxies aren't just bigger solar systems; they're held together by a different force, governed by different timescales, observed at different resolutions. The metaphor gives you permission to talk about scopes that aren't the same shape, and that permission is what the design discussions actually need.

This is the third metaphor piece in the series, and it complements rather than recapitulates the atoms-and-molecules and periodic-table pieces. Atoms-and-molecules is about composition. The periodic table is about layout. This one is about containment, how to think about nested scopes when the nesting isn't a single uniform recursion.

What the parent/child framing hides

The reason "tenant" and "sub-tenant" travels so well is that it sounds like it covers everything. Customer, business units, teams, users. One word, one nesting, problem solved.

Then you ship and the questions start. Compliance asks where the audit boundary is. Finance asks where billing combines. Security asks where the isolation guarantees apply, is data leakage between sub-tenants of the same parent a CVE or a configuration choice? Customer success asks why a sub-tenant admin can or can't see the parent's audit log. Engineering asks why role inheritance walks up the parent chain in some places and stops at the immediate tenant in others.

Each of these is asking about a different kind of scope. Compliance scope is one thing, billing scope is another, isolation scope is a third, and hierarchy scope is a fourth. The flat parent/child model gives you one axis to answer all of them on, so every answer becomes "well, it depends", the architectural smell of having forced four boundaries through one variable.

Those four scopes don't always align. Two sub-tenants under the same legal entity (same compliance scope) might be billed separately, isolated at the storage layer, but share an SSO directory. The parent/child model doesn't have words for that. The cosmological one does.

The layered model

Walking the metaphor in the order I find useful, outermost to innermost:

Universe. The deployment region or jurisdiction. Universes don't talk to each other directly. Data created in one doesn't flow into another except through deliberate interfaces. The EU universe and the US universe are separate. The dedicated-cloud universe for the bank that bought your enterprise tier is separate from the shared-cloud universe everyone else lives in. The universe is where data residency, base-layer compliance regime, and "is the network reachable" live.

Galaxy. The compliance and contractual scope. A galaxy is a legal entity (or a tightly coupled group of them) bound by one BAA, one DPA, one master agreement. Inside a galaxy, you can move data around with the agreed safeguards. Across galaxies, you can't, you need a separate contract or a fresh consent. A galaxy never spans universes; the data-residency boundary is harder than the contract boundary.

Solar system. The billing and account scope. A solar system is what gets one invoice. It's the unit your CRM treats as the customer. It has a primary star (the master account) and orbiting planets that share its gravity. One galaxy can contain several solar systems, because the same legal entity can have several billing accounts. The solar system is also where rate-limit pools, plan-level feature flags, and seat counts apply.

Planet. The hierarchy and ownership scope. A planet is a workspace, a team, a project, a tenant in the narrower sense most engineers use the word, where users live and day-to-day permission decisions happen. Planets have moons (sub-projects, channels, whatever your product's atomic container is). Many planets can share a solar system; planet-to-planet permissions are a deliberate design choice, not a default.

Operating environment. The execution and isolation scope. An environment is the runtime context: prod, staging, dev, the per-customer ephemeral environment that came up when somebody clicked "evaluate." Environments are scoped to a planet but not the same as one, a single planet typically has several environments, and the rules about which can read which other are explicit, not inherited.

That's five layers, not two. The discipline is that every scope-related design decision lives at exactly one of those layers, and the layer is named, not implied.

Why the bigger metaphor unlocks better discussions

What changes when you put the model on the whiteboard isn't the architecture. It's the vocabulary the room uses to argue about the architecture. That sounds soft. It's not. Most of the bad calls I've watched on multi-tenant systems came from a meeting where two engineers were using the same word for different scopes and didn't realize it for forty-five minutes.

A few of the discussions that get sharper:

Compliance vs. billing. Once "galaxy" and "solar system" are different words, it stops being controversial that the BAA covers three solar systems but isn't the unit of billing. The BAA lives at the galaxy. The invoice lives at the solar system. One-to-many, no schema crisis.

Isolation vs. hierarchy. A planet might have a hard isolation boundary while still belonging to a solar system that combines billing across many planets. Isolation lives at the planet's environments; hierarchy lives at the planet-to-solar-system relationship. They aren't the same thing.

Federation across galaxies. When two enterprise customers want to share data through your product, the question "what scope does the federation cross?" is now answerable. It crosses galaxies. That tells you the contract layer needs to be real, the audit boundary needs to be explicit on both sides, and the shared data needs to be tagged with its galaxy of origin. With "tenant" and "sub-tenant," that conversation devolves into "we'll add a shared_with array" within ten minutes.

Role inheritance. The one I see broken most often. Roles inherit along the hierarchy axis (planet → solar system) but not along the compliance axis. The parent/child model lets people quietly assume a transitive admin role across boundaries it shouldn't cross. That assumption is how you get the postmortem where the parent-tenant admin could see audit logs they had no contractual basis to see.

The same engineer who circles for an hour using "tenant" and "sub-tenant" reaches the right call twice as fast with the cosmological vocabulary on the wall, because the vocabulary forces the layered structure into the open instead of letting it stay implicit.

Where the metaphor connects to the rest of the work

The cosmological model isn't a replacement for the multi-tenant cost analysis or the migration playbook. It's the framing that makes them coherent. The argument in why multi-tenant is twice as expensive as you estimated is that the costs live in the surrounding systems (auth, audit, query routing, observability, billing) not in the application code. Notice that those systems each anchor at a different cosmological layer. Auth is planet-scope backed by galaxy-scope checks. Billing is solar-system scope. Audit is galaxy scope with planet-level enrichment. Query routing is environment scope. The 2x cost is what it costs to build each of those scopes correctly and keep them from leaking into each other. Without the layered model, you can't even name the work; with it, the line items become legible.

The migration playbook in the single-user to multi-tenant migration I actually shipped is also layered in disguise. Identity backfill lives at the planet. Dual-path enforcement spans planet-and-environment. The traffic shift is a solar-system decision. The deprecation ceremony is galaxy-level. The reason the migration succeeds when it's run as a posture rather than a release is that the layers move at different rates and you have to let them.

The connection to atoms-and-molecules and the periodic table is structural. The atoms in a multi-tenant system (a user, a workspace, an audit event, a billing line) each have a natural cosmological home. A user atom belongs to a planet; an audit event belongs to a galaxy; a billing line belongs to a solar system. Lay them out as a periodic-table grid by cosmological layer, and the families fall out, the planet-scoped atoms share one family, the galaxy-scoped ones share another, and the gaps in the grid (a galaxy-scoped audit type you haven't built yet but obviously need) light up the way Mendeleev's did.

The discipline, not the cosmology

The metaphor isn't load-bearing on its own. The discipline is: name your scopes, give each one a layer, refuse to let one variable do the work of four. Call them universe-galaxy-system-planet-environment, or region-entity-account-workspace-environment, or anything where the words are different enough that you can't accidentally collapse them. The point is that you have five words instead of two, and each one has a defended meaning.

I prefer the cosmological vocabulary because it travels well in a meeting and resists collapse. Nobody confuses a galaxy with a solar system the way they confuse a tenant with a sub-tenant. The friction in the words does work, it makes the layer boundary visible by making the substitution awkward.

Same point the other metaphor pieces in this series make: the framing you choose at the start of the design constrains what you can see later. A flat parent/child framing for multi-tenant ships something that works for the first ten customers and fails the moment a regulated customer asks an architecture question. A layered cosmological framing surfaces the four scopes early, makes them designable separately, and lets you answer the audit question without a forty-five-minute meeting.

Borrow the layers. Skip the astronomy. The point is the discipline of naming what you're containing, at what scale, under what rules, and refusing to let one word stand in for four.

, Sid