Core Concepts

Understanding the building blocks of Gatepost.

Projects

A project is the top-level container for your feature flags. Each project has:

• Unique ID - Used in the SDK to target the right flags
• Environments - e.g., development, staging, production
• Flags - All feature flags in the project
• Segments - Reusable targeting rules

Environments

Each project has multiple environments. Flags can have different values in each environment, allowing you to:

• Test changes in development before production
• Staged rollouts across environments
• Independent control per environment

Flags

A flag has:

• Key - Unique identifier used in code (e.g., new-checkout)
• Name - Human-readable label
• Type - boolean, string, number, or json
• Rules - Targeting rules for evaluation
• Rollout - Percentage-based user bucketing

Segments

Segments define reusable targeting rules. Create a segment once, then reference it across multiple flags.

Example segment:

{
  "key": "premium-users",
  "rules": [
    { "type": "attribute", "attribute": "plan", "operator": "equals", "value": "premium" }
  ]
}

Then use in any flag:

const enabled = await client.getBooleanValue("premium-feature", false, {
  segments: ["premium-users"]
});

Evaluation flow

1. Client sends flag key + attributes
2. Gatepost looks up flag in the specified environment
3. Rules are evaluated in order (top to bottom)
4. First matching rule returns its value
5. If no rules match, fallback to rollout percentage
6. If no rollout, return default value