Type

Status

Owner

Related Documents

API Design SpecAgent Runbook — Feature FlagsArchitecture Decision Records

414 words2 min read2,886 chars

●Saved

# Feature Flags Architecture

## Overview

This document defines the architecture for our feature flag evaluation system. The system provides real-time targeting, gradual rollouts, and instant kill-switch capabilities across all product surfaces.

See [[API Design Spec]] for the REST endpoints used to fetch flag states, and [[Agent Runbook — Feature Flags]] for operational procedures.

## Core Concepts

### Flag Evaluation Engine

The evaluation engine processes flags in the following order:

1. **Kill switch** — immediate override, highest priority
2. **Targeting rules** — user/segment-based targeting
3. **Rollout percentage** — percentage-based gradual rollout
4. **Default value** — fallback when no rules match

### Flag Types

| Type | Description | Use Case |
|------|-------------|----------|
| Boolean | Simple on/off | Feature visibility |
| String | Multi-variant | A/B testing copy |
| Number | Numeric value | Rate limits, thresholds |
| JSON | Structured config | Complex configurations |

## Architecture

```
SDK → Edge Evaluation → Flag Store → Rules Engine
         ↓
    Local Cache (TTL: 30s)
         ↓
    Event Stream (flag evaluations)
```

## Targeting Rules

Targeting rules are evaluated in priority order. Each rule contains:

- **Attribute** — user property to match (userId, email, plan, country)
- **Operator** — equals, contains, regex, semver
- **Value** — the match target
- **Variation** — which variant to serve

### Example Rule (YAML)

```yaml
rules:
  - attribute: plan
    operator: equals
    value: enterprise
    variation: enabled
  - attribute: email
    operator: contains
    value: "@acme.com"
    variation: enabled
```

## Rollout Strategy

Gradual rollouts use deterministic hashing on `userId + flagKey` to ensure:

- Consistent assignment per user across sessions
- No reassignment when percentage changes upward
- Sticky experiences within a single rollout

See [[Rollout Strategy]] for the mathematical model.

## SDK Integration

The SDK fetches flag states at initialization and subscribes to a streaming endpoint for real-time updates. See [[SDK Integration Guide]] for language-specific implementations.

```agent-context
# Context: Feature Flag System
This system controls feature visibility across all product surfaces.
Agents working on feature development should check flag states before
assuming feature availability in production.
```

## Performance

- **P50 evaluation latency**: 0.4ms (local cache hit)
- **P99 evaluation latency**: 12ms (cache miss, edge fetch)
- **Flag store sync interval**: 30 seconds
- **Event batching**: 500ms window, max 100 events

## Related Documents

- [[API Design Spec]] — REST API for flag management
- [[Agent Runbook — Feature Flags]] — Operational runbook
- [[Architecture Decision Records]] — ADR for flag system selection
- [[LaunchDarkly ADR]] — Vendor evaluation decision

Type / for commandsType [[ for wikilinks⌘S Save · ⌘⇧P Command palette

Feature Flags Architecture

Overview

See ⟦ API Design Spec ⟧ for the REST endpoints used to fetch flag states, and ⟦ Agent Runbook — Feature Flags ⟧ for operational procedures.

Core Concepts

Flag Evaluation Engine

The evaluation engine processes flags in the following order:

Kill switch — immediate override, highest priority

Targeting rules — user/segment-based targeting

Rollout percentage — percentage-based gradual rollout

Default value — fallback when no rules match

Flag Types

| Type | Description | Use Case | |------|-------------|----------| | Boolean | Simple on/off | Feature visibility | | String | Multi-variant | A/B testing copy | | Number | Numeric value | Rate limits, thresholds | | JSON | Structured config | Complex configurations |

Architecture

``SDK → Edge Evaluation → Flag Store → Rules Engine ↓ Local Cache (TTL: 30s) ↓ Event Stream (flag evaluations)`

`Targeting Rules`

Targeting rules are evaluated in priority order. Each rule contains:

Attribute — user property to match (userId, email, plan, country)


Operator — equals, contains, regex, semver
Value — the match target
Variation — which variant to serve
Example Rule (YAML)

`yaml rules: - attribute: plan operator: equals value: enterprise variation: enabled - attribute: email operator: contains value: "@acme.com" variation: enabled`

`Rollout Strategy`

Gradual rollouts use deterministic hashing on userId + flagKey to ensure:

Consistent assignment per user across sessions


No reassignment when percentage changes upward
Sticky experiences within a single rollout
See ⟦ Rollout Strategy ⟧ for the mathematical model.
SDK Integration
The SDK fetches flag states at initialization and subscribes to a streaming endpoint for real-time updates. See ⟦ SDK Integration Guide ⟧ for language-specific implementations.

`agent-context

`Context: Feature Flag System`


This system controls feature visibility across all product surfaces.
Agents working on feature development should check flag states before
assuming feature availability in production.

Performance

P50 evaluation latency: 0.4ms (local cache hit)

P99 evaluation latency: 12ms (cache miss, edge fetch)

Flag store sync interval: 30 seconds

Event batching: 500ms window, max 100 events