Core Concepts

FlagBridge organizes feature flags around a few core concepts. Understanding them helps you design a clean flag architecture.

Projects

A project is the top-level container. Typically one project per application or service.

Projects
└── my-app
    ├── Environments (production, staging, development)
    └── Flags (new-checkout-flow, dark-mode, ...)

Each project has its own API keys scoped to specific environments.

Environments

Environments let you control flags independently across your deployment stages. Every project comes with three default environments:

Environment	Typical use
production	Live traffic
staging	Pre-release testing
development	Local development

A flag enabled in staging is completely independent of the same flag in production. This means you can safely test flags before enabling them for real users.

Flags

A flag is a named boolean (or multi-variant) toggle. Each flag has:

• Key — unique identifier used in your code (e.g., new-checkout-flow)
• Name — human-readable label
• Status — enabled or disabled per environment
• Targeting rules — optional conditions for partial rollouts
• Variants — optional named values beyond true/false

Flag keys

Flag keys are immutable after creation. Use kebab-case (new-checkout-flow, not newCheckoutFlow).

Targeting rules

Targeting rules let you enable a flag for a subset of users without enabling it for everyone.

Rules are evaluated in order. The first matching rule wins.

Rule 1: userId IN [alice, bob]  → enabled
Rule 2: country = "BR"          → enabled
Default:                        → disabled

Context

The evaluation context is the set of attributes you pass when evaluating a flag. These are matched against your targeting rules.

{
  "userId": "user-123",
  "email": "user@example.com",
  "country": "BR",
  "plan": "pro",
  "beta": true
}

Any attribute can be used in targeting rules. Common attributes: userId, email, country, plan, orgId.

INFO

Context attributes are not stored by FlagBridge unless you enable analytics. They're used only for rule evaluation.

Percentage rollouts

Percentage rollouts gradually expose a flag to a percentage of users based on a consistent hash of their user ID.

• 10% rollout → same 10% of users always see the flag enabled
• Increasing from 10% to 20% adds users, never removes them (monotonic)

Variants

Variants (multi-variate flags) return a named string value instead of a simple boolean. Use them for A/B tests or configuration values.

{
  "flagKey": "checkout-button-color",
  "variant": "green",
  "enabled": true
}

Variant flags still have an "enabled" state — if the flag is disabled, the SDK returns the default variant.

Evaluation order

When a flag is evaluated, FlagBridge applies this precedence:

1. Test overrides — per-session overrides for E2E testing (always wins)
2. Targeting rules — evaluated in order, first match wins
3. Percentage rollout — applied if no targeting rule matched
4. Default — the flag's base enabled/disabled state

Plugins CE

Plugins extend FlagBridge with custom evaluation logic, analytics integrations, and more. Plugins can:

• Add custom targeting operators
• Emit evaluation events to analytics tools
• Sync flag state from external systems

See the Plugins overview for details.