Core concepts and mental model for feature flags with Flaggr

Concepts

This page covers the core ideas behind feature flagging and how Flaggr models them. Read this before the Quick Start to build a solid mental model.

What is Feature Flagging?

Feature flags (also called feature toggles) let you change application behavior without deploying new code. A flag wraps a code path and decides at runtime which path to take, based on rules you configure in Flaggr.

if (await client.getBooleanValue("checkout-v2", false)) {
  renderNewCheckout();
} else {
  renderOldCheckout();
}

Common Use Cases

Use Case	How Flags Help
Progressive rollouts	Ship to 5% of users, then 25%, then 100% — with instant rollback
A/B testing	Serve different variants to measure conversion, revenue, or engagement
Kill switches	Disable a feature in production in seconds, no deploy needed
Trunk-based development	Merge incomplete features behind a flag — the flag stays off until the feature is ready
Entitlements	Gate premium features by user plan, role, or organization
Operational controls	Adjust rate limits, cache TTLs, or algorithm parameters without redeploying

Data Model

Flaggr organizes everything in a three-level hierarchy:

┌─────────────────────────────────────────────┐
│  Project                                    │
│  (tenant isolation — your org or team)      │
│                                             │
│  ┌───────────────┐  ┌───────────────┐       │
│  │  Service A    │  │  Service B    │       │
│  │  (web-app)    │  │  (api)        │       │
│  │               │  │               │       │
│  │  ┌─────────┐  │  │  ┌─────────┐  │       │
│  │  │ Flag 1  │  │  │  │ Flag 3  │  │       │
│  │  │ Flag 2  │  │  │  │ Flag 4  │  │       │
│  │  └─────────┘  │  │  └─────────┘  │       │
│  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────┘

Projects

A project is the top-level container. It provides tenant isolation — each project has its own members, roles, API tokens, services, and flags. Typical mapping: one project per organization or product.

Services

A service represents an application or microservice within a project. Flags belong to a service. When your SDK evaluates a flag, it specifies which service to query.

Examples: web-app, mobile-ios, checkout-api, recommendation-engine.

Flags

A flag (feature flag) controls a single decision point. Every flag has:

Property	Description
key	Unique identifier within a service (e.g., `checkout-v2`)
type	`boolean`, `string`, `number`, or `object`
enabled	Master on/off switch
defaultValue	Value returned when no targeting rules match
environment	Which environment this flag configuration applies to
targeting	Rules that determine which users get which value
variants	Named value options for multi-variant flags

Environments

Every flag exists independently in three environments:

Environment	Purpose
`development`	Local development and testing
`staging`	Pre-production validation
`production`	Live user-facing traffic

A flag can be enabled in staging but disabled in production. Each environment has its own targeting rules, rollout percentages, and overrides. When your SDK connects, it specifies which environment to target.

See Environments for details.

Evaluation Flow

When your application calls client.getBooleanValue("checkout-v2", false), here's what happens:

1. SDK sends evaluation request
   → flag key, evaluation context, service ID, environment

2. Flaggr resolves the flag
   a. Look up the flag by key + service + environment
   b. Check if the flag is enabled (if not → return default value)
   c. Check overrides (identity-level pinning)
   d. Check prerequisites (dependent flags)
   e. Evaluate targeting rules top-to-bottom
   f. Apply rollout percentage (consistent hashing)
   g. Return matched variant or default value

3. SDK returns the resolved value to your code

Evaluation Reasons

Every evaluation includes a reason explaining how the value was determined:

Reason	Meaning
`TARGETING_MATCH`	A targeting rule matched
`DEFAULT`	No rules matched; returned default value
`DISABLED`	Flag is disabled
`OVERRIDE`	An identity override was applied
`SPLIT`	Percentage rollout assigned this variant
`PREREQUISITE_FAILED`	A prerequisite flag didn't match
`MUTUAL_EXCLUSION`	Another flag in the exclusion group won
`ERROR`	Evaluation failed; returned default value

OpenFeature Compatibility

Flaggr implements the OpenFeature specification — an open standard for feature flag evaluation. This means:

Vendor-neutral SDKs — Use any OpenFeature-compatible SDK (TypeScript, Go, Java, Python, and more)
Standardized evaluation context — Same context shape across all providers
Provider abstraction — Swap Flaggr for another provider without changing application code
Hooks and events — Standard lifecycle hooks for logging, metrics, and validation

Flaggr supports multiple evaluation protocols:

Protocol	Best For
REST API	Any language, simple integration
Connect-RPC	Type-safe, streaming, recommended for Go/TypeScript
OFREP	OpenFeature Remote Evaluation Protocol
SSE	Real-time flag updates in browsers
gRPC	High-performance server-to-server

Key Terminology

Term	Definition
Targeting rule	A condition (or set of conditions) that determines which users receive a specific flag value
Evaluation context	Attributes about the current user/request (user ID, plan, country, etc.) passed to the evaluator
Targeting key	The primary identifier in the evaluation context (usually user ID)
Variant	A named value option for a flag (e.g., `control`, `treatment-a`, `treatment-b`)
Rollout percentage	The fraction of users who see a particular variant, determined by consistent hashing
Override	An identity-level pin that forces a specific value for specific users
Prerequisite	A flag dependency — flag B only activates if flag A returns the expected value
Cohort	A reusable audience segment (rule-based, static list, or externally synced)
Mutual exclusion group	A set of flags where only one can be active for a given user
Progressive rollout	A staged deployment plan (5% → 25% → 50% → 100%) with safety checks