Design a Feature Flag SDK – Frontend System Design

We’ll walk through the frontend system design for a client feature-flag SDK and the admin UI that authors flags. You’ll see why the SDK evaluates a downloaded ruleset in memory, how to put the right variant on the first frame, how targeting and percentage rollouts stay deterministic, and where sticky assignments, kill switches, typed flags, cache, and privacy sit.
The interviewer usually phrases it as “design LaunchDarkly” or “design a feature-flag SDK”. A if (flag) renderV2() wrapper takes five minutes. The real question is the rest: a page that paints before the ruleset arrives, a 10% rollout that must not reshuffle on reload, a kill switch that cannot wait for the next poll, and a public client key, so the ruleset cannot hold your VIP email list.
Problem Statement
Design a JavaScript feature-flag SDK for a large web app, plus the admin UI that manages flags.
Requirements:
- Flags evaluate locally. A render must not wait on the network.
- The first paint uses the correct variant. No flicker of the old UI.
- Target users by attributes and named segments.
- Percentage rollouts are deterministic and sticky when the percentage grows.
- Operators can kill a flag instantly.
- Flags are typed. A boolean cannot silently become a string.
- The SDK caches the ruleset and respects privacy.
Describe the client architecture, the evaluation model, bootstrap, and the admin publishing path.
Interviewers are checking three things. Do you refuse remote-per-flag evaluation, or do you ship a spinner around every gated button? Do you understand the browser’s loading sequence well enough to explain why a useEffect fetch still flashes? And do you treat the client ruleset as public data, not a secret store?
Clarifying Questions
| # | Question | Interviewer’s Answer |
|---|---|---|
| 1 | Web only, or also React Native and SSR? | Web SPA plus Next-style SSR. Same evaluator, two boot paths. |
| 2 | How many flags, and how many does a page read? | ~500 in prod. A page reads ~40. A few are critical for first paint. |
| 3 | Real-time updates? | Poll the ruleset every 30s. Kill switches must land in a few seconds. |
| 4 | Anonymous visitors? | Yes. Sticky rollouts use a device id, not an email. |
| 5 | Who is in the targeting lists? | Plan, country, app version, and named segments. Not raw email lists in the browser bundle. |
| 6 | Experiments and metrics? | Impression events only. A full experiment platform is out of scope. |
| 7 | Environments? | local, staging, prod. Client key per environment, publishable. |
Question 1 decides bootstrap: SSR can evaluate into the HTML, a cached SPA cannot. Question 2 sets ruleset size. Question 5 forces segment membership onto the context, not into the downloaded JSON.
Requirements
Functional
- Boolean, string, number, and JSON flags, each with a default and a closed set of variations.
- Local evaluation from a versioned ruleset: kill switch, individual targets, ordered rules, then a percentage fallthrough.
- Attribute matchers: equals, in, contains, semver, numeric compare. Rules AND their clauses. First matching rule wins.
- Percentage rollout by a deterministic hash of salt, flag key, and user key.
- Sticky assignments so a contraction or a rule reshuffle does not bounce a user between variants.
- Identify: swap the context when a user signs in, re-evaluate, keep the anonymous id for merge if the product wants it.
- Subscribe to a single flag or to all changes. Kill switch notifies immediately.
- Admin UI to create flags, edit rules, preview a user, promote across environments, and disable in one click.
Non-Functional
- Zero frames painted with the wrong variant for critical flags (checkout, paywall, nav, theme).
- Evaluate 40 flags in well under 1ms on a mid-range laptop. No network on the read path.
- Ruleset under 50 KB gzipped. Cached across visits.
- Kill switch visible in under 5 seconds, including a tab that was already open.
- Client key is public. The ruleset must not leak PII or secrets.
- Typed access in application code. A renamed flag is a compile error after codegen.
“Zero wrong frames” shapes the client. The assignment must be known before paint, which pushes it out of React effects and into the HTML or a tiny <head> script. Same loading problem as Design a Theme Switcher, different data.
Napkin Math
| Metric | Estimate | Calculation | So what? |
|---|---|---|---|
| Ruleset size | ~200 KB raw, ~40 KB gzip | 500 flags × ~400 bytes | Download once. Do not fetch per flag. |
| Evaluate 40 flags | < 0.5 ms | 40 × a few clauses + one hash | Cheaper than one layout. Memoize by version. |
| Poll every 30s | 0 bytes if unchanged | ETag / 304 | A body download is the rare case. |
| Kill payload | ~1 KB | flag keys that are off | Poll every 5s or push over SSE. |
| Flash without a fix | ~1.3 s, ~80 frames | Ruleset at 2.4 s minus first paint at 1.1 s | A client-only fetch is not a fix. |
| Sticky store | ~4 KB | 50 records × ~80 bytes | Fits in localStorage. |
| Impression events | ~40 / session | One per flag read, sampled | Send flag + variation + anonymous key. |
Architecture
A control plane publishes the ruleset. A data plane only reads it. The SDK never calls GET /flags/checkout-v2 while rendering.
| Layer | Owns | Runs | Talks to |
|---|---|---|---|
| Admin UI | Rule builder, preview, kill, audit | Internal web app | Flag API |
| Flag API | Validation, versioning, env promotion | Server | Store, CDN, kill channel |
| Ruleset CDN | Per-env JSON, ETag, long cache | Every poll / SSR boot | Edge and browsers |
| SSR / Edge | Evaluate into HTML, inline bootstrap | Each HTML request | Session, ruleset cache |
| Head script | Critical assignments on cached HTML | Before <body> parses |
localStorage, <html> |
| FlagClient | Context, get, subscribe, identify | Client singleton | Evaluator, stores, app |
| Evaluator | Pure assign(flag, context, ruleset) | In memory | Sticky store |
Notice what is missing: there is no per-flag HTTP client inside a component. React reads a value that is already in memory. When a kill switch arrives, the evaluator runs again and subscribers update. That is a state change, not a loading state.
“The SDK downloads a ruleset and evaluates locally. A flag read is a function call. Bootstrap puts that function’s answer on the first frame. The client key is public, so the ruleset cannot hold PII.”
If the interviewer asks why not evaluate on the server for every flag: remote evaluation makes every gated render a network dependency, forces a loading UI, and still flickers unless you wait to paint. Use remote evaluation only for flags whose rules must stay secret. Everything else is local.
Data Model
A flag is data, not a remote key the client queries. The published artifact is a versioned ruleset the evaluator can run without the admin API.
type FlagType = "boolean" | "string" | "number" | "json";
type Reason = "off" | "target" | "rule" | "rollout" | "fallthrough" | "sticky" | "error";
type ClauseOp = "eq" | "neq" | "in" | "contains" | "gt" | "lt" | "semverGte";
interface Clause {
readonly attribute: string;
readonly op: ClauseOp;
readonly values: readonly string[];
readonly negate?: boolean;
}
interface Rule {
readonly id: string;
readonly clauses: readonly Clause[]; // AND
readonly rollout: readonly { variationId: string; weight: number }[]; // /10_000
}
interface Flag<T = unknown> {
readonly key: string;
readonly type: FlagType;
readonly enabled: boolean; // kill switch
readonly variations: readonly { id: string; value: T; name: string }[];
readonly rules: readonly Rule[];
readonly fallthrough: Rule["rollout"];
readonly offVariation: string;
readonly salt: string;
readonly version: number;
readonly sticky: boolean;
}
interface EvaluationContext {
readonly key: string; // user or device
readonly anonymous: boolean;
readonly attributes: Readonly<Record<string, string | number | boolean | readonly string[]>>;
}
interface Assignment<T = unknown> {
readonly flagKey: string;
readonly value: T;
readonly variationId: string;
readonly reason: Reason;
readonly version: number;
}
interface StickyRecord {
readonly flagKey: string;
readonly variationId: string;
readonly value: unknown;
readonly assignedAt: string;
}
interface Ruleset {
readonly env: "local" | "staging" | "prod";
readonly version: number;
readonly flags: Readonly<Record<string, Flag>>;
readonly etag: string;
}
Four choices are worth defending.
Weights in parts per 10,000, not integers of 100. A 2.5% rollout is bucket < 250. Interviewers notice when you only allow whole percents.
Salt lives on the flag, not on the environment. Two flags that both roll out to 10% must not put the same users in both treatments. Changing the salt reshuffles; that is a deliberate break-glass action, not the default when you edit a rule.
The context is the only place user data lives at eval time. The ruleset names attributes (plan, country, segment:beta). It does not list emails. Membership of a private segment is a boolean the server already put on the context.
Type is immutable after create. Changing a boolean flag into a string is a new flag. The admin UI locks the type. Codegen emits a union per key so getBoolean(“search-algo”) does not compile.
Local Evaluation
Evaluation is a pure function of (flag, context, sticky). No I/O. The first matching step wins.
The evaluator is a pure evaluate(flag, context, sticky) function in the SDK core, and the admin preview ships the same module. It returns an Assignment carrying the variation, its value, the reason, and the flag version. The steps run in a fixed order:
- Kill switch. A disabled flag returns its off variation with reason
off. - Sticky. If the flag is sticky and the stored variation still exists, return it with reason
sticky. - Individual target. If the context carries a
target:<flagKey>claim naming a real variation, return it with reasontarget. - Rules. Compute the user’s bucket once. For each rule in order, if every clause holds (with list attributes matched element-wise and
negateapplied last), walk the rule’s weighted rollout until the cumulative weight passes the bucket. The first hit returns with reasonrule. - Fallthrough. Apply the same weighted pick to the fallthrough rollout. If the weights don’t cover the bucket (a misconfigured flag), return the off variation with reason
errorrather than throwing.
The bucket is a 32-bit FNV-1a hash of salt.flagKey.userKey over UTF-16 code units, modulo 10,000. FNV-1a is tiny, fast, and easy to reimplement identically in every server language that evaluates the same ruleset.
Walk the interviewer through the hash.
It is deterministic. Same salt, flag, and key always land in the same bucket. Math.random() splits a user across tabs. That is noise, not a rollout.
Raising 10% to 50% keeps the original 10%. Bucket 0–999 stays inside 0–4999. You do not need sticky storage for an expansion.
The sticky store is for cases the hash cannot save. Dropping 50% to 10% kicks buckets 1000–4999 out. Changing the salt reshuffles everyone. A new clause set can move a user. If flag.sticky is on, keep the last variation until the flag is archived or stickiness expires.
Individual targeting is a context claim (target:checkout-v2 = “on”), not user ids in the ruleset. The admin still shows a list. Publish turns that list into membership on identify, or a signed cookie SSR can read. The downloaded JSON never contains the list.
Bootstrap and the Flash of Incorrect Variant
The flicker has one cause: the browser painted a default before it knew the assignment. The common mistake is useFlag(“checkout-v2”, false) plus a fetch in useEffect. Effects run after paint. On a mid-range phone that is more than a second of the old checkout. Decide before first paint. A large app uses both paths below, because SSR and CDN-cached pages are different.
Path A: SSR evaluates into the HTML
The edge already has the ruleset in memory (revalidated by ETag). The request carries ff_uid and, after sign-in, a session. The server builds a context, evaluates the critical flags, renders the matching markup, and inlines the bootstrap payload the client will reuse.
interface Bootstrap {
readonly ruleset: Ruleset;
readonly context: EvaluationContext;
readonly assignments: Readonly<Record<string, Assignment>>;
}
The server renderer keeps a short, explicit list of critical flags (checkout, paywall, nav). For each one present in the ruleset, it runs the shared evaluator, stores the assignment, and emits a data-ff-<key>="on|off" attribute for the <html> tag. It returns those attributes plus the serialized bootstrap, with every < escaped as u003c before it goes into the inline script.
Escape the JSON so a string variation cannot break out of the <script>. ff_uid is opaque, not an email. The client must init({ bootstrap }) with this object so the first React render matches the server HTML. A default of false is a hydration mismatch, then a visible swap. Cookie-varied HTML is fine for the signed-in app (Cache-Control: private). It is not fine for marketing pages.
Path B: cached assignments in the head
Static pages are identical for everyone, so the server cannot stamp per-user attributes. Persist the last critical assignments on the device and apply them with a classic inline script in the <head>, before any stylesheet that keys off those attributes.
The script runs inside a try. It reads one small JSON map of critical assignments from localStorage (ff.critical), and for each critical boolean that is true it sets the matching data-ff-* attribute on the root. Missing or corrupt storage leaves the defaults. It carries a CSP nonce, and the app stylesheet comes after it.
Do not parse a 200 KB ruleset and run the full evaluator on the critical path. That script blocks parsing. It reads a few booleans and writes a few attributes. The full SDK then boots from IndexedDB, re-evaluates, and only notifies if a value changed.
Every property of the script is deliberate, and it is the same list as the theme-switcher script: inline, classic, before the stylesheets, wrapped in try, tiny, allowed by a CSP nonce or hash. A module, a defer, or a useEffect can run after first paint.
What the React binding must look like
The hook is useFlag(key, fallback), built on useSyncExternalStore. It subscribes to the client for that one key and reads client.get(key, fallback) as its snapshot. The same read function serves as the server snapshot.
The server snapshot and the client snapshot are the same function: read from the bootstrap the SSR already inlined. There is no “default until ready” path for critical flags. Non-critical flags may return the fallback until client.ready() if you accept a late swap; say that out loud so the interviewer knows you scoped the zero-flicker rule.
| Strategy | Wrong frames | CDN-cacheable HTML | Needs JS |
|---|---|---|---|
Fetch in useEffect |
Hundreds of ms or more | Yes | Yes, late |
| Wait to paint until ready | Zero, but a blank page | Yes | Yes |
| Head script + last assignments | Zero | Yes | ~400 bytes, early |
| SSR bootstrap | Zero | No (varies per user) | No for first paint |
The Client SDK
The SDK is a singleton outside React. It owns the ruleset, the context, the sticky store, and the poller. Components only call get and subscribe.
Its public surface is small, and every method is synchronous except boot.
- Construct with an optional bootstrap. The context comes from the bootstrap, or is an anonymous context keyed by a persistent device id. Bootstrap assignments seed the memo, so the first
getreturns exactly what the server rendered. get(key, fallback)returns the memoized assignment’s value, evaluating on a miss, or the fallback if the flag doesn’t exist. A sticky flag records its assignment on first evaluation.identify(context)swaps the context and recomputes every flag.applyKill(keys)produces a new ruleset with those flags disabled and their versions bumped, adopts it, and recomputes.- Adopt (internal) installs a ruleset, clears the memo, and rewrites the critical assignments for the head script.
- Recompute (internal) evaluates every flag again and notifies only the subscribers of flags whose variation actually changed.
Point out a few things in the interview.
getnever returns a Promise. A Promise puts a loading state on every gated component.ready()is for boot, not for reads.- Memo keys include the ruleset version and the context key. Identify and kill both recompute.
- Impressions fire once per
(flag, variation, session), from the evaluator, not from every React render. - The device id is created on first visit and reused. That is what makes an anonymous 10% rollout stable. Do not join it to email.
Typed flags
Do not hand authors get(key: string, fallback: unknown). Generate the catalog from the published schema.
// generated from the prod schema, committed or built in CI
export interface FlagMap {
"checkout-v2": boolean;
"search-algo": "v1" | "v2" | "v3";
"max-upload-mb": number;
}
Codegen also emits a defaults object typed as FlagMap and typed getters like getBoolean, whose key parameter accepts only the keys whose type is boolean. The default lives next to the type, so a component can’t pass a different fallback than the one product agreed on.
The admin refuses to change a flag’s type. A new type is a new key. That is how codegen stays honest across clients.
Cache, Polling, and Kill Switches
There are four caches, and they have different jobs.
| Store | Holds | Read on | Invalidated by |
|---|---|---|---|
| Memory | Ruleset + memo | Every get |
New version, identify, kill |
| IndexedDB | Full ruleset JSON | Next visit, before network | ETag change |
localStorage |
Critical assignments, sticky, device id | Head script, evaluator | Recompute, archive |
| CDN | Per-env ruleset | SSR and poller | Publish (new ETag) |
The poller does GET /rulesets/prod.json with If-None-Match. Unchanged is a 304. Changed is a new body: adopt it, recompute, and notify the keys that moved. Thirty seconds is fine for ordinary edits. It is not fine for a broken checkout.
A kill switch is a separate, tiny channel. Disable sets enabled: false, publishes a one-kilobyte overlay, and fans it out over SSE (or a 5s poll). The SDK calls applyKill() immediately. The next full poll reconciles versions so a tab that missed the push still converges. Do not hide the kill bit in the 30s JSON, and do not put every edit on the kill channel. That path stays small so it can be loud.
Admin UI
The admin is a form over the data model. The published ruleset is the contract the SDK already understands.
- Flag list. Search, type, environment, on/off. Virtualize it; 500 live previews will stutter.
- Rule builder. Ordered AND clauses, first match wins. The slider writes weights that sum to 10,000. Preview the hash: “user
u_123is bucket 1840, so at 25% they are in.” - Targeting preview. Run the same
evaluate()the SDK ships. If admin and SDK drift, the preview lies. - Promotion. Staging and prod are two documents. Promote copies a version. The local key never points at prod.
- Type lock and kill. Type is chosen at create. Kill is one confirm, then the overlay, not “set fallthrough to 0%” on the 30s poll.
- Audit. Who published which version. Humans need this after a bad rollout. The SDK does not.
The dangerous feature is a textarea of emails written into the client JSON. Gate it: the list becomes a server-side segment attached on identify, or the flag is remoteOnly. Show that warning. Interviewers listen for it.
API
// Control plane (admin session, CSRF)
GET /api/flags?env=prod
POST /api/flags
PATCH /api/flags/:key
POST /api/flags/:key/kill // enabled=false + overlay
POST /api/flags/:key/promote
POST /api/preview // { env, context } -> Assignment[]
// Data plane (publishable client key)
GET /rulesets/:env.json // If-None-Match, max-age=30
GET /kills/:env.json // max-age=5
GET /sse/kills/:env
interface FlagClientPublic {
ready(): Promise<void>;
get<T>(key: string, fallback: T): T;
getBoolean(key: keyof FlagMap): boolean;
subscribe(key: string, fn: Listener): () => void;
identify(ctx: EvaluationContext): void;
}
type Impression = {
flagKey: string;
variationId: string;
reason: Reason;
contextKey: string; // anonymous or hashed
rulesetVersion: number;
};
The client key downloads the ruleset and nothing else. It cannot write flags, read audits, or fetch another environment. Rotate it like a public analytics write key. Impressions go to your collector, sampled: flag, variation, reason, non-email key, ruleset version. That answers “what percent saw v2?” without shipping attributes off the device.
State and Data Flow
- First request. SSR reads
ff_uidand session, evaluates critical flags, writes attributes and bootstrap JSON. - Head script. On cached HTML, applies last critical assignments before paint.
- SDK boot.
init({ bootstrap })or IndexedDB, thenGETwith ETag. No visual change if the version matches. - Identify. New context, recompute. Namespace sticky records by context key so an anonymous draw does not follow a new account.
- Publish / kill. A normal edit is a new ETag within 30s. A kill is an overlay in seconds, then persist so the next visit stays off.
Cross-tab: a storage listener on the critical-assignment key is enough. You do not need BroadcastChannel.
Optimizations
| Problem | Technique | Effect |
|---|---|---|
| Flicker before fetch | SSR bootstrap + head-script assignments | Correct variant on frame one |
| Per-flag HTTP | One ruleset, local eval | Reads are function calls |
| Re-evaluating in render | Memo by flag, version, context key | One hash per change, not per render |
| Hydration mismatch | Same bootstrap on server and client | No swap, no React warning |
| 30s kill latency | Tiny overlay + SSE or 5s poll | Off in a few seconds |
| Repeat visits | IndexedDB ruleset + ETag | First paint does not wait on CDN |
| Fat ruleset | Drop archived flags, split remote-only flags | Stays near 40 KB gzip |
Do not evaluate all 500 flags at boot. Evaluate on first read, memoize, and precompute only the critical list. Most flags are never read on a given page. In the Performance panel you should see the head script, first paint already treated, then a 304. A layout shift when the ruleset arrives means a critical flag took the late path.
Handling Edge Cases
- Storage disabled. Head script and sticky store no-op. SSR still has the cookie. Anonymous rollouts become per-session.
- Unknown flag or type mismatch. Return the fallback, reason
error, do not throw in render. Log once. CI should have failed codegen already. - Clock skew. Evaluation ignores client time. Scheduled start/end belongs in the ruleset version, or the edge and the tab disagree at the boundary.
- Identify after an anonymous rollout. Switch to the user key and namespace sticky records so the anonymous 10% does not lock a new account into the wrong treatment.
- Multiple tabs, one kill. Overlay plus the
storageevent. A background tab applies before its next paint. - App version. Send
appVersionfrom the build. Use a real semver compare, not string greater-than.
Testing
Treat the evaluator as a pure unit: table-driven cases for expansion, contraction, sticky hit, kill, and a context that matches nothing. Playwright covers bootstrap: SSR HTML already treated, static page with seeded localStorage has the attribute before load. A test that waits for the network, then asserts the button, will pass a flickering implementation.
Accessibility, Privacy, and Security
Accessibility
- Gated UI that appears or disappears must not steal focus. A kill that removes a nav item moves focus to a landmark.
- Do not flag the only path to a setting without a keyboard-reachable fallback.
- The rule builder is a real form: labelled clauses, an announced preview, a kill confirm that names environments.
- Percentage sliders need a numeric input. 2.5% is a typed value, not a pixel on a track.
Privacy
Local evaluation is the privacy feature, not just a performance feature. User attributes never leave the device to decide a flag. Guard the rest of the pipeline so you do not throw that away.
- The client ruleset is public. No emails, phones, account ids, or “internal only” names in clauses.
- Private segments are server-computed booleans on the context. The ruleset says
segment:beta eq true. - Impressions use the device id or a hashed user key, never the attribute map.
- The device id is first-party. Clearing site data draws a new bucket, which is acceptable.
- GDPR deletion removes sticky records and impressions. The ruleset has nothing to delete.
Security
- Client keys are publishable. Write keys never go into the browser bundle.
- Bootstrap JSON is escaped (
<to\u003c) before it sits in a<script>. - The head script is allowed by nonce or hash, never
’unsafe-inline’. - Admin mutations are CSRF-protected and audited. Kill is privileged. Preview does not log PII.
For a broader look at what you can safely put in a browser bundle, see Frontend Security Best Practices.
What a Strong Answer Sounds Like
| Topic | Junior answer | Senior answer |
|---|---|---|
| Evaluation | Fetch each flag from the server | Download a ruleset, evaluate in memory, memoize by version |
| First paint | Show a spinner, then the flag | SSR bootstrap plus a head script for cached HTML; no default-then-swap |
| Rollout | Math.random() < 0.1 |
Deterministic hash; expansions stay stable; sticky store for contractions |
| Kill switch | Wait for the next poll | Tiny overlay or SSE, apply immediately, persist so the next visit stays off |
| Privacy | Not mentioned | Client key is public; PII lists never ship in the ruleset |
The flicker problem is the same loading-sequence question as theming. For the broader client architecture, see Design a Scalable Frontend Architecture.
Conclusion: How to Design a Feature Flag SDK
Start with local evaluation. A flag read is a pure function of a downloaded ruleset, a context, and an optional sticky record. Percentage rollouts use a hash so raising 10% to 50% keeps the original users. The sticky store exists for the cases that hash cannot save. The client key is public, so targeting lists that would leak PII never enter the browser bundle.
Then make the assignment a fact about the first paint, not about a fetch. Evaluate on the server and inline a bootstrap object, or apply last critical assignments with a tiny classic script in the <head>. Hydration reads that same snapshot. A kill switch rides a small, fast channel, not the 30 second ruleset poll. If you can explain why a useEffect fetch still flashes, why an expansion does not need sticky storage, and why an email allowlist cannot live in the client JSON, you have answered the question the interviewer actually asked.
