Feature Flags
Data Entity
Description
Per-organization feature toggle records that allow Organization Administrators to enable or disable specific platform capabilities independently of code deployments. Each flag maps to a known feature key from the static feature registry and stores the override state for a single organization.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for this feature flag record | PKrequiredunique |
organization_id |
uuid |
Reference to the organization this flag override belongs to | required |
feature_key |
string |
Identifier matching a known key in the static feature registry (e.g. 'expense-reimbursement', 'calendar-sync', 'gamification-wrapped') | required |
enabled |
boolean |
Whether this feature is currently enabled for the organization. Defaults to the registry default when no override exists. | required |
metadata |
json |
Optional JSON object for feature-specific configuration parameters (e.g. rollout percentage, variant selection, A/B test group) | - |
enabled_by |
uuid |
User ID of the administrator who last toggled this flag | - |
enabled_at |
datetime |
Timestamp when the flag was last enabled or disabled | - |
description_override |
text |
Optional org-specific description override displayed in the admin toggle UI | - |
created_at |
datetime |
Timestamp when this flag record was first created | required |
updated_at |
datetime |
Timestamp of the most recent update to this record | required |
Database Indexes
idx_feature_flags_org_key
Columns: organization_id, feature_key
idx_feature_flags_organization_id
Columns: organization_id
idx_feature_flags_feature_key
Columns: feature_key
idx_feature_flags_enabled
Columns: organization_id, enabled
Validation Rules
feature_key_format
error
Validation failed
organization_must_exist
error
Validation failed
enabled_is_boolean
error
Validation failed
metadata_json_valid
error
Validation failed
enabled_by_must_be_valid_user
error
Validation failed
no_duplicate_flag_override
error
Validation failed
Business Rules
unique_flag_per_org
Each organization can have at most one override record per feature_key. The unique index on (organization_id, feature_key) enforces this at the database level.
feature_key_must_exist_in_registry
The feature_key must match a known entry in the static feature registry. Unknown keys are rejected to prevent orphaned or misspelled flags.
org_admin_or_global_admin_only
Only Organization Administrators and Global Administrators may create, update, or delete feature flags. Coordinators and Peer Mentors have read-only access via cached flag lookups.
toggle_change_audit_logged
Every enable/disable action must produce an audit log entry recording the actor, organization, feature_key, old value, and new value for compliance traceability.
cache_invalidation_on_change
When a flag is created, updated, or deleted, the Redis cache entry for the organization's flags must be invalidated so subsequent reads reflect the new state within the 60-second TTL window.
default_from_registry_when_no_override
If no feature_flags record exists for a given (organization_id, feature_key) pair, the system returns the default enabled state from the static feature registry. An explicit record is only created when an admin overrides the default.
tenant_isolation
Feature flag queries must always be scoped to the requesting user's organization. Global Admins can query any organization's flags but cannot bulk-toggle across organizations in a single operation.
session_bootstrap_includes_flags
All enabled feature flags for the user's organization are included in the session bootstrap payload so the mobile app and admin portal can evaluate flags client-side without additional API calls.