Dev Note

Feature Flags at Scale: Beyond the Toggle — Architecture Patterns for 2026
Every team starts with a simple feature flag: if config.ENABLE_NEW_CHECKOUT: .... It works. Then you have 50 flags. Then 500. Then you’re debugging a production incident caused by flag interaction, or your product team is asking why their A/B test results are unreliable, or an engineer accidentally changed a flag that affects 10% of users. Feature flag systems that start simple accumulate enormous operational complexity — and most teams figure this out the hard way.
This post covers the architecture patterns that make feature flag systems maintainable and reliable at scale.
Photo by Markus Winkler on Unsplash
The Four Categories of Feature Flags
Martin Fowler’s taxonomy remains the clearest framework:
1. Release Toggles — Decouple deploy from release. Code ships dark, flag enables it when ready.
2. Experiment Toggles — A/B tests, multivariate experiments. Statistical analysis drives decisions.
3. Ops Toggles — Kill switches for degraded functionality. Built for operators, not product managers.
4. Permission Toggles — Feature access by user segment, subscription tier, or geography.
The mistake most teams make: treating all four categories identically. They have different lifecycles, different evaluation semantics, and different performance requirements.
Core Architecture: Evaluation Service
The feature flag evaluation engine is the center of your system. Its requirements:
Latency: P99 < 5ms (in-process evaluation, not network calls)
Throughput: Handle millions of evaluations per second
Consistency: Same context → same result (within a session)
Graceful degradation: Fall back to defaults on service outage
The Flag Context Object
Design your context schema carefully — it’s hard to change later:
interface EvaluationContext {
  // Required
  userId: string;
  
  // Targeting dimensions
  organizationId?: string;
  userAttributes: {
    email?: string;
    plan?: 'free' | 'pro' | 'enterprise';
    country?: string;
    createdAt?: Date;
    [key: string]: unknown;
  };
  
  // Request context
  requestId: string;
  sessionId: string;
  appVersion?: string;
  platform?: 'web' | 'ios' | 'android' | 'api';
  
  // Override for testing/debugging
  forcedVariations?: Record<string, string>;
}
Flag Definition Schema
interface FeatureFlag {
  key: string;                    // 'new_checkout_flow'
  type: 'boolean' | 'string' | 'number' | 'json';
  category: 'release' | 'experiment' | 'ops' | 'permission';
  
  defaultValue: FlagValue;        // Returned if evaluation fails
  
  rules: EvaluationRule[];        // Ordered list, first match wins
  
  metadata: {
    owner: string;
    createdAt: Date;
    expiresAt?: Date;             // Auto-archive after this date
    jiraTicket?: string;
    description: string;
  };
}
interface EvaluationRule {
  conditions: Condition[];        // AND logic within a rule
  percentage?: number;            // 0-100 for percentage rollouts
  bucketBy?: string;             // Field to hash for consistency
  variation: FlagValue;
}
Consistent Bucketing: The Most Misunderstood Part
Percentage rollouts must be consistent — the same user must always see the same variation within a rollout, across sessions, across services.
The standard approach: hash ${flagKey}:${userId} to a deterministic bucket:
import hashlib
def get_bucket(flag_key: str, bucket_by_value: str) -> float:
    """Returns a float in [0, 1) for consistent bucketing."""
    hash_input = f"{flag_key}:{bucket_by_value}".encode("utf-8")
    hash_bytes = hashlib.md5(hash_input).digest()
    # Use first 4 bytes as an unsigned int
    bucket_int = int.from_bytes(hash_bytes[:4], byteorder='big')
    return bucket_int / (2**32)
def evaluate_percentage_rule(
    flag_key: str,
    context: EvaluationContext,
    rule: EvaluationRule
) -> bool:
    bucket_value = getattr(context, rule.bucket_by, context.user_id)
    bucket = get_bucket(flag_key, str(bucket_value))
    return bucket < (rule.percentage / 100.0)
Why md5(flagKey:userId) and not just md5(userId)?
Using just userId means the same users always get new features first, biasing your experiments. The flag key in the hash ensures independent distribution across flags.
Targeting Rule Evaluation
A rule-based evaluator:
def evaluate_flag(flag: FeatureFlag, context: EvaluationContext) -> FlagValue:
    # Check for forced override (QA/debugging)
    if context.forced_variations and flag.key in context.forced_variations:
        return context.forced_variations[flag.key]
    
    # Evaluate rules in order
    for rule in flag.rules:
        if all(evaluate_condition(c, context) for c in rule.conditions):
            if rule.percentage is None:
                return rule.variation
            
            bucket_by = getattr(context, rule.bucket_by or 'user_id', context.user_id)
            bucket = get_bucket(flag.key, str(bucket_by))
            
            if bucket < rule.percentage / 100.0:
                return rule.variation
    
    return flag.default_value
def evaluate_condition(condition: Condition, context: EvaluationContext) -> bool:
    attribute_value = resolve_attribute(context, condition.attribute)
    
    match condition.operator:
        case "equals":
            return attribute_value == condition.value
        case "in":
            return attribute_value in condition.value
        case "not_in":
            return attribute_value not in condition.value
        case "contains":
            return condition.value in str(attribute_value)
        case "semver_gte":
            return semver_compare(attribute_value, condition.value) >= 0
        case "before":
            return parse_date(attribute_value) < parse_date(condition.value)
        _:
            return False
Operational Patterns
Flag Delivery: Push vs Pull
 
      Pull (Polling)
      Push (Streaming/SSE)
    
Staleness
      Config interval (e.g., 30s)
      Near-real-time
    
Complexity
      Simple
      Requires SSE/WebSocket infrastructure
    
Reliability
      Works without persistent connection
      Needs reconnect logic
    
Best for
      Most use cases
      Ops kill switches
    
For ops toggles that control degraded-mode behavior, near-real-time delivery matters. For release flags, 30-second polling is typically fine.
Local Caching with Fallback
class FlagEvaluator:
    def __init__(self, remote_source: FlagSource):
        self._remote = remote_source
        self._cache: dict[str, FeatureFlag] = {}
        self._last_sync: float = 0
        self._sync_interval = 30.0  # seconds
    
    def evaluate(self, flag_key: str, context: EvaluationContext) -> FlagValue:
        flag = self._cache.get(flag_key)
        
        if flag is None:
            # Unknown flag — return safe default, never raise
            logger.warning(f"Unknown flag: {flag_key}")
            return False
        
        try:
            return evaluate_flag(flag, context)
        except Exception as e:
            # Evaluation error — fall back to default, never propagate
            logger.error(f"Flag evaluation error for {flag_key}: {e}")
            return flag.default_value
    
    async def sync(self):
        """Called by background thread; failures don't affect evaluation."""
        try:
            flags = await self._remote.fetch_all()
            self._cache = {f.key: f for f in flags}
            self._last_sync = time.time()
        except Exception as e:
            logger.error(f"Flag sync failed: {e}")
            # Keep stale cache — degraded but functional
Observability: What to Track
Every flag evaluation should emit a metric:
def evaluate_with_tracking(
    flag_key: str,
    context: EvaluationContext
) -> FlagValue:
    result = self.evaluate(flag_key, context)
    
    # Emit to metrics/analytics
    metrics.increment(
        "feature_flag.evaluation",
        tags={
            "flag_key": flag_key,
            "variation": str(result),
            "user_plan": context.user_attributes.get("plan", "unknown"),
        }
    )
    
    return result
This data powers dashboards showing rollout progress, and feeds into experiment analysis.
Flag Lifecycle Management
The hardest operational problem: flags accumulate and never get cleaned up. After 2 years, you have 800 flags and nobody knows which are safe to remove.
Enforce a TTL at creation time:
# Flag definition with mandatory expiry
key: "new_dashboard_redesign"
category: "release"
expires_at: "2026-09-01"   # Required for all release/experiment flags
owner: "platform-team"
cleanup_ticket: "ENG-4521"
Automated staleness alerts:
def check_stale_flags():
    for flag in flag_store.all():
        if flag.expires_at and flag.expires_at < datetime.now():
            notify_owner(
                flag.owner,
                f"Flag '{flag.key}' expired {flag.expires_at}. "
                f"Please remove it: {flag.cleanup_ticket}"
            )
Build vs Buy
Tool
      Best For
      Key Differentiator
    
LaunchDarkly
      Enterprise, complex targeting
      Most mature, best tooling
    
Unleash
      Self-hosted, open source
      Full control, no vendor lock
    
Flagsmith
      Simple, open source option
      Easy to self-host
    
Statsig
      Experiment-heavy teams
      Stats engine built-in
    
AWS AppConfig
      AWS shops, simple flags
      Free, native AWS integration
    
GrowthBook
      A/B testing focus
      Open-source stats engine
    
Build your own only if: you have unique compliance requirements, extremely high evaluation volume (billions/day), or complex custom targeting logic.
The Ops Toggle Pattern: Your Production Safety Net
The most underutilized flag category. Every piece of degradable functionality should have an ops toggle:
def get_recommendations(user_id: str) -> list[Product]:
    if not flags.evaluate("recs_service_enabled", context):
        # Graceful degradation: return popular items
        return product_store.get_popular(limit=10)
    
    try:
        return recommendations_service.get(user_id)
    except ServiceUnavailableError:
        return product_store.get_popular(limit=10)
When the recommendations service has an incident, ops toggles that flag and the blast radius is contained immediately — no deploy required.
Conclusion
Feature flags are infrastructure. Treat them that way. The teams that handle them well share three characteristics:
Typed, schema-validated flag definitions — not ad-hoc config files
Mandatory expiration dates for release and experiment flags
Ops toggles on every degradable component
The technical patterns here are relatively standard. The discipline to enforce the lifecycle policies is where most teams fall short. Build the automation that enforces expiry, notifies owners, and archives dead flags — or the technical debt will compound into a maintenance nightmare.
References
Feature Toggles (aka Feature Flags) — Martin Fowler
LaunchDarkly Documentation
Unleash Open Source
Statsig Feature Gates

Feature Flags at Scale: Beyond the Toggle — Architecture Patterns for 2026

댓글