Feature Flags — Reference
The Feature Flags surface is the gated-toggle plane for SGEN. It owns the catalog of named flags configured on a site, the per-flag targeting rules (per-site, per-user, percentage rollout), the evaluation surface that resolves a flag's on / off state for a given context, the audit trail of every flip, and the read-side hooks that let other modules condition behavior on flag state. Anything that asks "is this capability on for this caller right now?" traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, extending the targeting model, or scoping a controlled rollout. Customer-facing how-tos for managing flags live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Feature Flags live under the Feature Flags module in SG-Admin. The module renders three primary views — the flag list (every configured flag on the site, with state and rule summary), the flag editor (a single flag's name, default state, targeting rules, rollout percentage, and notes), and the audit-trail view (the chronological list of every flip and rule change, per flag).
The module is paired by convention with the Users, Settings, and Activity Log surfaces. Targeting rules reference user records by id or by role slug; default-state rules reference the site context owned by Settings; every flip writes an Activity Log entry. The Feature Flags module owns the toggle and the targeting; the consuming surfaces own the records the rules point at.
A second surface — runtime evaluation — is exposed to other modules. When a module wants to gate a code path on a flag, it asks the Feature Flags surface "is flag X on for context Y" and receives a boolean plus the rule that produced it. The evaluation is deterministic for the same context inputs, side-effect-free, and cached per request.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Feature Flags
- URL prefix:
/sg-admin/feature-flags/ - View templates:
application/views/Admin/FeatureFlags/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Feature Flags [+ Add flag] │├──────────────────────────────────────────────────────────────────────┤│ Flag Default Rules Last flipped ││ ───────────────────────── ─────── ──────────── ──────────────────││ new-checkout-flow OFF 50% rollout 2 min ago ││ beta-media-pipeline ON Admins only 3 days ago ││ legacy-builder-fallback ON — 19 days ago ││ experimental-search OFF Per-user (4) now ││ ││ [⋯ Edit] [⋯ Audit trail] [⋯ Flip] [⋯ Archive] │└──────────────────────────────────────────────────────────────────────┘Actions
The Feature Flags surface exposes the following operations. Each is described by what it does to the data and to the evaluation contract, not by its internal method name.
List and search
Returns the flag records visible to the current operator, paginated, with name, default state, rule summary, last-flipped timestamp, and current evaluation count columns. Supports column sort, free-text filter on flag name and notes, and per-page count. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.
Create flag
Opens an empty flag form. Required fields at minimum: flag name (unique slug), default state (on or off), notes. Optional fields cover targeting rules, rollout percentage, and an expiry date for transient flags. On submit, the surface validates uniqueness of the slug, persists the record, and returns the new identifier. A newly created flag is immediately addressable from the evaluation surface — there is no separate publish step.
Edit flag
Loads an existing flag into the same form shape used for create, pre-populated. Submit replaces the stored configuration with the posted values. Rule order is preserved as authored — the evaluation surface walks rules top-to-bottom and stops at the first match. Fields left blank do not clear server-side values (the form is partial-update by default).
Flip flag
A dedicated write path that toggles the flag's default state without touching rules. Accepts an optional reason note that is stored on the audit-trail entry. Returns the new state. Flip is the fast path for an operator who needs to disable a misbehaving rollout without re-opening the editor — the rule chain is preserved and the flag can be flipped back without re-authoring.
Configure targeting rules
The targeting model is an ordered list of rules. Each rule pairs a match condition with a state outcome. Conditions cover: specific user id, user role slug, percentage of traffic (computed from a stable per-user hash), site context, and date / time window. The evaluation surface walks rules in order — the first matching condition resolves the flag to its outcome state; if no rule matches, the flag's default state applies.
Evaluate flag
The read-side contract other modules call. Inputs: flag slug, evaluation context (user id, role, site id, current timestamp). Output: boolean state plus the rule slug that produced it (or default if no rule matched). Evaluation is deterministic for the same inputs and is cached per request to keep the cost of repeated calls inside a single page load constant.
View audit trail
Returns the chronological list of every flip, every rule change, and every state transition for a single flag, with the acting operator and the change shape. The audit trail is append-only — entries cannot be edited or deleted. Used by operators investigating why a rollout produced an unexpected outcome.
Archive flag
Marks the record inactive without removing it from the database. Archived flags disappear from the default list view but remain queryable via the archive filter. Evaluation of an archived flag returns the default state and writes a warning entry to the audit trail — calling code should treat the warning as a signal to remove the flag check.
Restore archived
Reverses an archive. The record returns to the active list with its prior rules and state intact.
Permanent delete
Hard-removes the record. Available only after an archive. The audit trail for the deleted flag is retained as an orphan record (the flag slug is preserved but no longer resolves on evaluation). This path is irreversible.
Data model
A flag record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
slug | string | Unique. The identifier callers use to evaluate the flag. |
name | string | Display name for the list view. Not unique. |
default_state | boolean | Resolved when no rule matches. |
rules | ordered list | Each rule: { condition, outcome_state, note }. Order preserved. |
rollout_percentage | integer | Optional. 0-100. Resolved against a stable per-user hash. |
expiry_at | timestamp | Optional. Past expiry → list view flags the record. |
notes | string | Operator-facing description. Not surfaced to evaluation. |
status | enum | active or archived. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit or flip. |
user_id, role, percentage, site, date_window), an outcome state (on or off), and an optional note. Rules evaluate top-to-bottom — first match wins.Audit-trail attribution: every flip, every rule change, and every state transition writes an audit entry. The entry stores the acting operator id, the timestamp, the change shape (field-level diff), and an optional operator-supplied reason. Audit retention is governed by the site's Activity Log retention setting.
FLAG RECORD├── id integer primary key├── slug string unique evaluation identifier├── name string display├── default_state boolean resolved when no rule matches├── rules ordered [{condition, outcome_state, note}]├── rollout_percentage integer 0-100, stable per-user hash├── expiry_at timestamp optional, surfaces in list as warning├── notes string operator-facing description├── status enum active | archived└── timestamps created_at, updated_at↓ on flip / rule-change / archiveAUDIT TRAIL ENTRYoperator_id + timestamp + change shape + reason(append-only, retained per Activity Log policy)Permissions
Access to the Feature Flags surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Feature Flags surface.
Layer 2 — per-action capability. Within SG-Admin, each Feature Flags action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List flags | ✔ | ✔ | ✔ |
| Create flag | ✔ | — | — |
| Edit flag | ✔ | — | — |
| Flip flag | ✔ | ✔ | — |
| Evaluate flag (read-side) | ✔ | ✔ | ✔ |
| View audit trail | ✔ | ✔ | — |
| Archive | ✔ | — | — |
| Restore archived | ✔ | — | — |
| Permanent delete | ✔ | — | — |
Self-protection rules. A flag cannot reference itself in a rule condition (no circular evaluation). A flag with an expiry date in the past cannot be flipped on without first clearing or extending the expiry. The surface returns a structured rejection in each case.
Audit. Every write — create, edit, flip, rule change, archive, restore, delete — emits an Activity Log entry in addition to the per-flag audit trail. The Activity Log entry records the acting operator, the target flag, and a one-line summary. The per-flag audit trail records the full change shape.
EVALUATE REQUEST│ inputs: flag_slug + context (user_id, role, site_id, now)▼┌───────────────────────────┐│ Resolve flag record │ unknown slug → return default OFF + warn└─────────────┬─────────────┘│ active flag▼┌───────────────────────────┐│ Walk rules top-to-bottom │ per-rule: condition matches context?│ stop at first match │└─────────────┬─────────────┘│┌──────┴──────┐│ match │ no match▼ ▼outcome_state default_state│ │└──────┬──────┘▼return {state, rule_slug_or_default}│▼per-request cache (same inputs → same answer)Related references
- Users — Reference. Targeting rules reference user records by id and by role slug. Soft-deleted users still resolve in rules until the rule is updated.
- Settings — Reference. Owns the role definitions referenced by role-based rules, the Activity Log retention policy that governs audit-trail lifetime, and the site context referenced by per-site rules.
- Activity Log — Reference. Every flag write emits a one-line entry. The per-flag audit trail is a separate denser record kept under this module.
- Automations — Reference. Time-driven flag flips (a flag that flips on at a scheduled date) can be authored as an Automation with a flip-flag action — see the Automations action catalog.
- A/B Testing — Reference. Variant assignment is structurally similar to percentage-rollout targeting but lives in a separate module because it carries the conversion-tracking and significance-gate layer.
/docs/feature-flags.