Skip to main content

Core concepts and mental model for feature flags with Flaggr

Last updated November 14, 2026

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 CaseHow Flags Help
Progressive rolloutsShip to 5% of users, then 25%, then 100% — with instant rollback
A/B testingServe different variants to measure conversion, revenue, or engagement
Kill switchesDisable a feature in production in seconds, no deploy needed
Trunk-based developmentMerge incomplete features behind a flag — the flag stays off until the feature is ready
EntitlementsGate premium features by user plan, role, or organization
Operational controlsAdjust rate limits, cache TTLs, or algorithm parameters without redeploying

Data Model

Flaggr organizes everything in a three-level hierarchy:

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:

PropertyDescription
keyUnique identifier within a service (e.g., checkout-v2)
typeboolean, string, number, or object
enabledMaster on/off switch
defaultValueValue returned when no targeting rules match
environmentWhich environment this flag configuration applies to
targetingRules that determine which users get which value
variantsNamed value options for multi-variant flags

Environments

Every flag exists independently in three environments:

EnvironmentPurpose
developmentLocal development and testing
stagingPre-production validation
productionLive 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 a flag is evaluated on the control plane (POST /api/flags/evaluate on https://flaggr.dev), the request flows through this pipeline. The SDK's default endpoint, the data plane at https://api.flaggr.dev, is a separate Go service. It evaluates disabled flags, overrides, targeting rules, rollout percentages and variants, but doesn't apply prerequisites, mutual exclusion groups or experiments, and in_cohort and not_in_cohort conditions never match there.

The reason field in the response tells you exactly which step produced the value — see the table below.

Evaluation Reasons

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

ReasonMeaning
TARGETING_MATCHA targeting rule matched
DEFAULTNo rules matched; returned default value
DISABLEDFlag is disabled
OVERRIDEAn identity override was applied
VARIANTVariant allocation selected this value (OFREP reports it as SPLIT)
EXPERIMENTA running experiment assigned this variant (control plane only; OFREP reports it as SPLIT)
PREREQUISITE_FAILEDA prerequisite flag didn't match (control plane only)
MUTUAL_EXCLUSIONAnother flag in the exclusion group won (control plane only)
NOT_FOUNDNo flag with that key in the service and environment (the data plane says FLAG_NOT_FOUND)
ERROREvaluation 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:

ProtocolBest For
REST APIAny language, simple integration
Connect-RPCType-safe, streaming, recommended for Go/TypeScript
OFREPOpenFeature Remote Evaluation Protocol
SSEReal-time flag updates in browsers
gRPCHigh-performance server-to-server

Key Terminology

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

What's Next?