Feature Flag
Data Entity
Description
Per-organization runtime toggle controlling whether a named platform capability is enabled or disabled. Enables Norse Digital Products to gate features per organization independently, supporting phased rollouts, organization-specific customization, and operational kill-switches without code deployments.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key for the feature flag record | PKrequiredunique |
organization_id |
uuid |
Foreign key to the organization this flag is scoped to. Every flag record belongs to exactly one organization. | required |
feature_key |
string |
Machine-readable identifier for the platform capability being toggled. Must match a key registered in the static feature registry (e.g., 'bufdir_export', 'encrypted_assignments', 'gamification_wrapped'). Max 100 characters, lowercase with underscores. | required |
enabled |
boolean |
Whether the feature is currently active for this organization. Defaults to false for unknown or newly introduced keys. True means the feature is accessible to users in this org. | required |
metadata |
json |
Optional structured configuration payload accompanying the flag. Used for features that require org-specific parameters alongside the enabled/disabled state (e.g., rollout percentage, allowed user IDs for beta access, custom thresholds). Schema is feature-key-specific and validated at the service layer. | - |
set_by_user_id |
uuid |
ID of the admin user who last changed this flag state. Null if set by system default. Used for audit trail correlation. | - |
created_at |
datetime |
Timestamp when this flag record was first created for the organization. Auto-set on insert, never updated. | required |
updated_at |
datetime |
Timestamp of the most recent change to this flag record (enabled toggle or metadata update). Auto-updated on every write. | required |
Database Indexes
idx_feature_flag_org_key
Columns: organization_id, feature_key
idx_feature_flag_org_id
Columns: organization_id
idx_feature_flag_key
Columns: feature_key
idx_feature_flag_enabled
Columns: organization_id, enabled
Validation Rules
feature_key_format
error
Validation failed
feature_key_format_update
error
Validation failed
organization_id_exists
error
Validation failed
metadata_json_validity
error
Validation failed
metadata_json_validity_update
error
Validation failed
unique_org_key_pair
error
Validation failed
enabled_not_null
error
Validation failed
Business Rules
registry_key_enforcement
A feature_key value may only be persisted if it exists in the static feature registry loaded by feature-registry-loader. Keys not present in the registry are rejected at the service layer before hitting the database. This prevents orphaned flags for features that were renamed or removed.
org_admin_scope_restriction
Only an Org Admin may create or update feature flags scoped to their own organization. A Global Admin may read and modify flags for any organization. Coordinators and Peer Mentors have no write access. Requests that violate this rule are rejected with a 403 before database interaction.
org_admin_scope_restriction_update
Same scope enforcement applies on updates — an Org Admin may only toggle flags for their own organization_id.
cache_invalidation_on_write
Any create, update, or delete on a feature_flag record must trigger invalidation of the corresponding org-level flag map in Redis via feature-flag-cache-adapter. The 60-second TTL cache must not serve stale data after an admin toggle. Invalidation is performed synchronously before the API response is returned.
cache_invalidation_on_delete
Deletion of a flag record (reverting to registry default) must also invalidate the Redis cache entry for the organization.
upsert_semantics
Flag records are managed via upsert — if a record for (organization_id, feature_key) already exists, it is updated; otherwise it is inserted. This prevents duplicate flag records and simplifies the admin toggle flow.
default_disabled_for_unknown_keys
When feature-flag-checker evaluates a flag for a feature_key that has no database record for the given organization, it returns false (disabled) without error. This ensures safe defaults when new features are deployed before org admins have explicitly configured them.
api_middleware_enforcement
Every inbound API request to a feature-gated endpoint must have the relevant feature flag checked via feature-flag-service before the handler executes. Requests to disabled features return 403 or 404 depending on the feature's visibility policy.
mobile_bootstrap_propagation
The full feature flag map for the authenticated user's organization must be included in the session bootstrap payload at login, so the mobile app can gate UI features client-side without additional round-trips.