What is a cell based architecture, and how is a cell different from a shard or an availability zone?

A cell is a complete, independently deployable copy of your service stack: compute, databases, queues, caches and configuration. Each cell serves a fixed subset of tenants. A request for tenant acme is handled entirely inside one cell. It does not fan out to others, and no other cell holds acme's data. Because each cell is self-contained, a bad deploy, a poisoned cache or a runaway query only affects the tenants assigned to that cell.

Two terms are often confused with cells:

Shard Availability zone Cell
What is partitioned Data only Physical infrastructure Entire stack plus data
Failure it contains Hot or oversized partition Power, network or facility outage Software, config, deploy and load failures
Shared across units App tier, caches, queues Everything above the hardware Only the routing layer and a minimal control plane
Deployed independently No No Yes

A sharded database behind a shared application tier still has one blast radius, because one bad release breaks every shard at once. Zones isolate hardware faults but run identical software, so a defect spreads to all of them. For this reason a cell should usually span several zones. Zones handle infrastructure failure inside the cell, and cells handle software and tenant failure across the fleet. These are separate dimensions of isolation.

The request path is short. A client hits a thin cell router, which looks up the tenant in a routing table and forwards the request to the owning cell. Copying the stack is mostly an infrastructure-as-code problem. The hard engineering is in routing, tenant placement and migration, and the rest of this article covers those.

                                +--------+
                                | Client |
                                +---+----+
                                    | request for tenant acme
                                    v
 +------------------------------------------------------------------------+
 | Cell router: look up tenant in routing table, forward to owner         |
 | acme -> cell-1    globex -> cell-2    ...                              |
 +------------------------------------------------------------------------+
                  |                                     |
                  v                                     v
 +----------------------------------+  +----------------------------------+
 | Cell 1: acme, initech, ...       |  | Cell 2: globex, umbrella, ...    |
 | +--------+ +--------+ +--------+ |  | +--------+ +--------+ +--------+ |
 | | zone a | | zone b | | zone c | |  | | zone a | | zone b | | zone c | |
 | +--------+ +--------+ +--------+ |  | +--------+ +--------+ +--------+ |
 | | app    | | app    | | app    | |  | | app    | | app    | | app    | |
 | | db pri | | db rep | | db rep | |  | | db pri | | db rep | | db rep | |
 | | queue  | | queue  | | queue  | |  | | queue  | | queue  | | queue  | |
 | | cache  | | cache  | | cache  | |  | | cache  | | cache  | | cache  | |
 | +--------+ +--------+ +--------+ |  | +--------+ +--------+ +--------+ |
 | own deploy pipeline, own config  |  | own deploy pipeline, own config  |
 +----------------------------------+  +----------------------------------+
                  |                                     |
 +------------------------------------------------------------------------+
 | Minimal control plane: tenant placement, migration, routing updates    |
 +------------------------------------------------------------------------+

A thin router maps each tenant to exactly one cell. Each cell is a full stack that spans several availability zones. The only components the cells share are the routing layer and a minimal control plane.

Why use cells? Blast radius reduction as arithmetic

The case for cells is mostly arithmetic. If a fault stays inside one of N roughly equal cells, it reaches about 1/N of your tenants instead of all of them.

Illustrative estimate. Assume 20 cells and 4,000 tenants, placed evenly at about 200 per cell. A bad config push or a poison-pill request that takes down one cell affects about 200 tenants, roughly 5% of the customer base. Without cells, the same fault reaches all 4,000.

Tenants are rarely equal, though. Suppose one cell holds a single tenant that generates 30% of platform traffic. Losing that cell is still "5% of tenants," but it is closer to a third of your load, and possibly more of your revenue. The useful measure is each cell's share of traffic, revenue, or contractual SLA exposure, not its tenant count. That pushes placement toward balancing weight, and it may justify giving the largest tenants dedicated cells.

Per-cell exposure only pays off if deploys respect cell boundaries. Roll out one cell at a time. Start with a canary cell that holds internal or low-risk tenants. Let each wave bake long enough for slow failures to surface, such as memory growth or queue backlog. Halt automatically when per-cell error rate, latency, or saturation crosses its threshold. Comparing a cell against its own baseline catches regressions that a fleet-wide average would hide.

The cost is time. Twenty cells with a bake period between waves can turn a deploy into a day-long process. Urgent security fixes need an explicit fast path, such as larger waves or shorter bakes. Use of that path should require approval and be logged, so it doesn't become the default route.

How does tenant routing work in a cell based architecture?

The partition key is almost always the tenant ID. It is the unit you want to isolate, it is stable for the life of the tenant, and nearly every request already carries it in some form. Avoid user ID or region as the key: a single tenant's users would scatter across cells, and one tenant's incident would leak into several cells.

The router can read the tenant identifier from several places, and each one carries different trust implications:

Source Example Trust level Notes
Subdomain acme.example.com Low until resolved Easy to route on at the edge, but a lookup does not prove the caller belongs to that tenant
Path /t/acme/orders Low Same as subdomain; trivially editable
Token claim tenant_id in a signed JWT High Trustworthy only after the router verifies the signature and expiry
Header X-Tenant-ID None from clients Safe only when the router itself sets it after validation

Never trust a client-supplied header. If the router accepts it, any caller can steer requests into another tenant's cell, and the cell may treat the request as already authorized. Strip the inbound header at the edge, derive the tenant from a verified source, and re-inject the header for downstream services.

Some requests have no tenant yet. Signup and pre-login discovery ("which tenant is this email in?") go to a small global service that owns the tenant-to-cell mapping. Global admin and billing aggregation also stay outside the cells. They should read from per-cell exports or an aggregated store, not fan out live queries into every cell.

import { importSPKI, jwtVerify } from "jose";

// Paths that run before a tenant is known, or span all tenants, go to the global service.
const GLOBAL_PATHS = ["/signup", "/login", "/discover", "/admin", "/billing"];
const GLOBAL_UPSTREAM = "global-svc.internal:8080";

// In practice this is a cached copy of the global tenant-to-cell mapping.
const cellForTenant = new Map([["acme", "cell-03"], ["globex", "cell-07"]]);

const publicKey = importSPKI(process.env.JWT_PUBLIC_KEY_PEM ?? "", "RS256");

export async function route(host: string, path: string, inbound: Record<string, string>) {
  // Never trust a client-supplied tenant header: drop it before doing anything else.
  const headers = { ...inbound };
  delete headers["x-tenant-id"];

  if (GLOBAL_PATHS.some((p) => path.startsWith(p))) {
    return { upstream: GLOBAL_UPSTREAM, headers };
  }

  const auth = headers["authorization"];
  if (!auth?.startsWith("Bearer ")) throw new Error("401: missing token");

  // jwtVerify checks the signature and exp; the claim is only trusted after this succeeds.
  const { payload } = await jwtVerify(auth.slice(7), await publicKey, {
    issuer: "auth-service",
    audience: "app-api",
  });
  const tenantId = payload.tenant_id;
  if (typeof tenantId !== "string") throw new Error("401: no tenant claim");

  // The subdomain is a routing hint only; reject if it disagrees with the verified claim.
  if (host.split(".")[0] !== tenantId) throw new Error("403: tenant mismatch");

  const cell = cellForTenant.get(tenantId);
  if (!cell) throw new Error("404: unknown tenant");

  // Re-inject the header only now, so downstream services can rely on it.
  headers["x-tenant-id"] = tenantId;
  return { upstream: `${cell}.internal:8080`, headers };
}

A minimal router function that removes any client-sent X-Tenant-ID header, sends pre-login and cross-tenant paths to the global service, takes the tenant from a verified JWT claim, rejects a subdomain that disagrees with that claim, and re-injects the header before forwarding to the tenant's cell.

How should you design the cell router and its routing table?

The router has one job: extract the tenant key (subdomain, token claim, or header), look up the cell, and forward the request. Business logic does not belong there. Feature flags, rate-limit tiers, and request rewriting all make the router a component that every tenant depends on and that changes often, which recreates the shared blast radius cells were meant to remove. For the same reason, deploy the router more conservatively than the cells. Use slower rollouts, longer bake times, and fewer releases, because a bad router build affects every cell at once.

Approach Lookup cost Moving one tenant Main risk
Central lookup table One cached read Edit one row Table store becomes a dependency
Consistent hashing Pure computation Not possible without moving others Adding cells reshuffles tenants
Hash plus override table Override check, then hash Add an override row Two sources of truth to reason about

Hash plus overrides works well when most tenants are placed by default and only a few are pinned or migrating.

Treat the mapping as versioned data. Each record should carry the tenant ID, cell ID, a monotonically increasing version, the time it was updated, and who changed it. Routers cache the full mapping and refresh it in the background. If the store is unreachable, they keep serving from the last known good version instead of failing closed. Stale routing for a few minutes is far less damaging than rejecting all traffic. Keeping version history gives you an audit trail and lets you roll back by reapplying the previous version.

import hashlib
import logging

# Versioned override record as kept in the mapping store (history retained for audit/rollback):
# {"tenant_id": "acme-co", "cell_id": "cell-07", "version": 1842,
#  "updated_at": "2026-10-30T14:12:00Z", "updated_by": "ops@example.com"}

CELLS = ["cell-01", "cell-02", "cell-03", "cell-04"]

class TenantRouter:
    def __init__(self, store):
        self.store = store      # exposes fetch_overrides() -> (version, {tenant_id: cell_id})
        self.version = None
        self.overrides = {}     # last known good override table

    def refresh(self):
        # Runs on a background timer, never on the request path.
        try:
            version, overrides = self.store.fetch_overrides()
        except Exception:
            # Store unreachable: keep serving the cached mapping instead of failing closed.
            logging.warning("mapping store unreachable; serving version %s", self.version)
            return
        # Only move forward. A rollback is published as a new version with the old contents.
        if self.version is None or version > self.version:
            self.version, self.overrides = version, overrides

    def cell_for(self, tenant_id):
        # Pinned or migrating tenants are resolved from the override table first.
        pinned = self.overrides.get(tenant_id)
        if pinned:
            return pinned
        # Default placement: rendezvous hashing, so adding a cell only moves the tenants it wins.
        return max(CELLS, key=lambda c: hashlib.sha256(f"{c}:{tenant_id}".encode()).digest())

# Request path: extract the key, look up the cell, forward. No business logic here.
# cell = router.cell_for(tenant_id_from_subdomain_or_token)

A thin router that checks a cached, versioned override table before falling back to rendezvous hashing, and keeps serving its last known good mapping when the store is unreachable.

How do you migrate a tenant between cells safely?

Migration is the hardest part of a cell based architecture because it is the one operation where a tenant's data briefly lives in two places and the routing layer must change its answer mid-flight. A safe sequence looks like this:

  1. Bulk copy the tenant's data from the source cell to the target cell while the source keeps serving traffic.
  2. Catch up using change data capture or dual writes until replication lag is near zero.
  3. Fence writes on the source for a short window. Reject or queue them so no new state lands after the final sync.
  4. Flip the routing entry by publishing a new mapping version that points the tenant at the target cell.
  5. Drain in-flight requests on the source, then lift the fence on the target.

Each step guards against a specific failure. If you skip the fence, writes land on the source after the final sync and are lost. If you replay change events that are not idempotent, you get duplicate writes. If the drain is slow or the fence is long, you get visible downtime. The versioned mapping lets you reject requests stamped with a stale version instead of silently writing to the wrong cell.

Build and rehearse this path before you need it. When you have to rebalance, isolate a noisy neighbor, or move a large tenant out, you will be under pressure, and that is the wrong time to test it for the first time.

Sizing

Set a maximum cell size from limits you have actually load-tested. When cells fill up, add new cells instead of growing existing ones. Very large "whale" tenants can get dedicated cells, but a dedicated cell gives them no blast radius benefit. Their own failure is still a total failure for them.

import threading

class StaleRoute(Exception): pass   # caller re-resolves the route and retries
class Fenced(Exception): pass       # caller backs off and retries shortly

class RoutingTable:
    def __init__(self, entries):
        self._lock = threading.Lock()
        self._map = dict(entries)   # tenant_id -> (cell_id, mapping_version)
        self._fenced = set()

    def lookup(self, tenant):
        with self._lock:
            return self._map[tenant]

    def set_fence(self, tenant, on):
        with self._lock:
            (self._fenced.add if on else self._fenced.discard)(tenant)

    def flip(self, tenant, target_cell, expected_version):
        # Compare-and-set: abort if the mapping changed under us.
        with self._lock:
            _, version = self._map[tenant]
            if version != expected_version:
                raise RuntimeError("concurrent mapping change; abort migration")
            self._map[tenant] = (target_cell, version + 1)

    def check_write(self, cell_id, tenant, stamped_version):
        # Every cell runs this before applying a write.
        with self._lock:
            if tenant in self._fenced:
                raise Fenced(tenant)
            if self._map[tenant] != (cell_id, stamped_version):
                raise StaleRoute(tenant)   # never write to the wrong cell

def migrate(table, tenant, target, bulk_copy, catch_up, final_sync, drain):
    source, version = table.lookup(tenant)
    bulk_copy(tenant, source, target)    # 1. source keeps serving traffic
    catch_up(tenant, source, target)     # 2. CDC replay; apply must be idempotent
    table.set_fence(tenant, True)        # 3. no new writes land on the source
    try:
        final_sync(tenant, source, target)
        table.flip(tenant, target, version)  # 4. publish mapping version + 1
        drain(tenant, source)            # 5. wait for in-flight source requests
    finally:
        table.set_fence(tenant, False)   # on failure, the old mapping still stands

A minimal in-process sketch of the migration sequence: writes are fenced before the final sync, the routing entry is flipped with a compare-and-set version bump, and each cell rejects writes stamped with a stale mapping version instead of applying them to the wrong cell.

What shared dependencies break cell isolation, and how do you observe cells?

Cells only limit blast radius if nothing underneath them is shared. Audit each cell's request path and dependency graph, and list every component outside the cell boundary. Common ones:

Dependency Why it crosses cells Typical decision
Global database or shared cache cluster One overload or failover hits every tenant Move into cells, or keep only for non-critical data
Central auth Every request depends on it Cache tokens and verify them locally in each cell
Shared message broker One backlog or partition stalls all consumers Run a broker per cell
Config and feature-flag service One bad push reaches everyone at once Keep global, but roll out changes cell by cell
DNS, deploy pipeline, control plane Needed to change or reach every cell Accept as global, with a stricter reliability budget

Any dependency you accept as global needs its own SLO set tighter than any single cell's. Its failure scope is the whole fleet, so it needs more margin.

Some failures still cross cells even with good isolation:

  • Global config push: a bad config applied everywhere at once breaks every cell together.
  • Poison-pill input: a payload that crashes a parser crashes it in every cell that receives it.
  • Regional outage: it takes down all cells co-located in that region.
  • Skipped wave gates: a deploy pipeline that bypasses its waves ships a bad build to every cell at once.

Observing cells

Tag every metric, log line and trace span with a cell_id label. Build an SLO dashboard and alerts for each cell. A fleet-wide average can look normal while one cell is failing, because the healthy cells dilute the bad one's error rate.

On-call should be able to answer "which cell is this tenant in, and is it healthy?" in one step. That means one lookup that joins the routing table with the health status of that cell.

When should you avoid cell based architecture, and what are the alternatives?

Cells pay off for multi-tenant SaaS with many tenants, strict availability targets, and a platform team that can already run many identical stacks from automation. Avoid them for small or single-tenant systems. Avoid them too if your workload depends on cross-tenant joins or globally unique constraints, such as usernames or invoice numbers, because each one becomes a cross-cell service you must build. If you cannot fund migration tooling, cells will harden into a fixed shard map.

Alternative What it contains What it leaves shared
Data sharding only Database load and storage Compute, caches, deploys
Zone or region redundancy Infrastructure failures Bad deploys and poison requests
Bulkheads and per-tenant rate limits Noisy neighbors within one stack Data tier, config, deploys
Shuffle sharding Overlap between tenants' failure sets Control plane, data stores
One well-run stack Nothing structurally Everything

The costs scale with cell count. You patch more databases, run more deploy waves, and maintain more dashboards. Every cell repeats the same fixed baseline cost. Global tables have to be retrofitted. Analytics, search, and reporting need their own aggregation paths, because no single database holds all the data anymore.

Cells save engineering time in other places. An incident affects one cell's tenants instead of all of them. A deploy runs in one cell before it reaches the rest. A noisy neighbor slows only its own cell. When you need more capacity, you add an identical cell rather than re-architecting a stack that has hit its ceiling.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to cell based architecture, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.