Multi-Tenant Feature Flag System Design: From Conditional to Platform

Northstar Cloud (fictional, for this module) ships one application to roughly 200 business customers — tenants. A new collaborative dashboard is ready. Tenant Atlas wants it on for everyone today. Tenant Birch wants a careful ten percent pilot, with beta testers always included. Tenant Cedar wants it off in production until a compliance review finishes, but on in their own staging environment.

This is not primarily a storage problem, even though it looks like one. A flags table with a boolean column already solves 'remember a value per tenant.' What it doesn't solve is: how does a value change without a redeploy, how does one tenant's targeting rule stay invisible to another tenant, how does a rollout percentage stay stable for the same user across requests and across app instances, and what happens to every request currently relying on this system when its central store is unreachable.

Scope this explicitly before any diagram — the scope decisions are half the design.

Functional (V1)

Create, edit, and target boolean and multivariate (string/number/JSON) flags, scoped to tenant, project, and environment. Targeting by explicit allow/deny, by segment membership, and by deterministic percentage rollout. Evaluation from backend services (full rule access) and from browsers (pre-evaluated values only). Every production change requires a review/approval step and is recorded in an audit trail. Administration and bulk analytics endpoints are explicitly out of scope for V1 evaluation-path design — this module focuses on the create → govern → distribute → evaluate pipeline, not a full admin-console feature set.

Non-functional

Start with the simplest thing that could possibly work: if (newDashboardEnabled), where the value is a build-time environment variable.

This is not a strawman. For a single-tenant internal tool, a compile-time constant is a completely legitimate V1. A feature flag platform earns its complexity later, by solving demonstrated problems — not by assumption.

The cracks appear the moment a second tenant wants different behavior. Turning the feature on for Atlas alone still means changing the environment variable and redeploying the entire fleet — there is no 'just for one tenant' at this layer, and every release becomes an all-or-nothing event for every tenant simultaneously.

Replace the compile-time constant with a flags table and a simple admin API. Each request resolves tenant plus environment plus flag key against the database. At low volume, this is a legitimate, shippable V1.

As usage grows, every request now pays a network round trip and a database query just to answer 'is this flag on' — a cost paid on the hot path of every single request, competing for the same database connections and I/O as the actual application logic. Flag-check volume is now a direct multiplier on database load rather than a near-free local operation.

Then the flags database has an outage — maintenance, connection-pool exhaustion, doesn't matter why. Every request that depends on a flag check now fails too, because the check is synchronous and sits in the critical path. A component whose entire job is to make releases safer has just become the reason the whole application is down.

Give the application a backend SDK. On startup it loads a snapshot of relevant flags into memory; after that, every evaluation is a pure, local, in-memory function call.

Introduce a real namespace: tenant → project → environment. Every flag definition, override, and published snapshot is scoped to this exact tuple.

A naive rollout calls Math.random() < 0.10 on every request. The same user flips between ON and OFF on consecutive requests — a bug, not a rollout.

Replace randomness with a deterministic hash of a stable tuple — tenant, project, environment, flag key, bucketing unit, the subject's stable ID, and a flag-specific salt — reduced to a uniform number, say zero to 99,999. In this illustrative example, User 42 at Birch hashes to bucket 7,314; the ten percent rollout covers buckets 0–9,999, so User 42 is ON, consistently, on every instance, because the inputs never change.

An edit is a draft until a reviewer approves it. Once approved, the control plane commits the durable change and writes an outbox event in the same transaction, so a snapshot builder can turn it into an immutable, versioned artifact — never a silent mutation of a previous version.

A control-plane outage must not interrupt an already-warmed SDK's evaluation — that's the entire payoff of moving evaluation local. A brand-new, cold instance with no snapshot yet is the one case that needs an explicit, documented startup-default policy per flag.

Rollback never rewrites history: an operator reverting a problematic rollout publishes a brand-new version whose content matches the last known-good configuration, and then watches version adoption across the fleet to confirm the rollback has actually reached production traffic.

Backend services can safely hold the full targeting rule set in memory. A browser is a different trust boundary — it receives only its own already-evaluated result, never the underlying segment definitions or other tenants' rules.

Every component below exists because of a specific, demonstrated failure earlier in this story. A small, single-tenant deployment may not need every piece at once.