Feature Flag Architecture at Scale

# flag-service/docker-compose.yaml
services:
  flag-service:
    image: your-org/flag-service:latest
    ports:
      - "8080:8080"     # REST API for management
      - "8081:8081"     # SSE stream for real-time updates
    environment:
      DATABASE_URL: postgres://flags-db:5432/flags
      REDIS_URL: redis://flags-cache:6379
      AUDIT_LOG_TOPIC: flag-changes
    depends_on:
      - flags-db
      - flags-cache
      - kafka

  flags-db:
    image: postgres:16
    volumes:
      - flags-data:/var/lib/postgresql/data

  flags-cache:
    image: redis:7
    # Cache for flag definitions - reduces DB load
    # SDKs also maintain their own in-memory cache

import json
import threading
from pathlib import Path

class FeatureFlagClient:
    def __init__(self, service_url, fallback_path="/etc/flags/defaults.json"):
        self._flags = {}
        self._lock = threading.Lock()
        self._service_url = service_url
        self._fallback_path = Path(fallback_path)

        # Try to connect; fall back to cached/default config
        try:
            self._flags = self._fetch_flags()
            self._start_streaming()
        except ConnectionError:
            self._flags = self._load_fallback()

    def is_enabled(self, flag_key, user_id=None, attributes=None):
        """Evaluate flag locally - no network call."""
        with self._lock:
            flag = self._flags.get(flag_key)
            if not flag:
                return False
            return self._evaluate(flag, user_id, attributes)

    def _evaluate(self, flag, user_id, attributes):
        if not flag["enabled"]:
            return False
        if flag["rollout"]["strategy"] == "percentage":
            bucket = hash(f"{flag['key']}:{user_id}") % 100
            return bucket < flag["rollout"]["percentage"]
        return flag.get("default", False)

    def _load_fallback(self):
        """Load baked-in defaults when flag service is down."""
        if self._fallback_path.exists():
            return json.loads(self._fallback_path.read_text())
        return {}

# Who changed the 'new-checkout' flag in the last 24 hours?
curl -s "http://flag-service:8080/api/audit" \
  --header "Authorization: Bearer $TOKEN" \
  --data-urlencode "flag=new-checkout" \
  --data-urlencode "since=24h" | jq '.events[] | {
    time: .timestamp,
    user: .changed_by,
    field: .field_changed,
    old: .old_value,
    new: .new_value
  }'

# Output:
# {
#   "time": "2026-04-01T14:23:00Z",
#   "user": "[email protected]",
#   "field": "rollout.percentage",
#   "old": "10",
#   "new": "50"
# }