Gate application features behind organization-specific flags at runtime
The feature-gate-widget wraps any UI element or navigation destination and consults the feature-flag-provider to determine visibility at render time. The rollout-evaluator applies the organization's flag configuration, including any percentage-based rollouts, to decide whether to render the child widget or replace it with nothing (or an alternative placeholder). This evaluation must be fast and synchronous for cached flags to avoid layout shifts. The feature-flag-initializer runs during app startup to pre-load all flags for the authenticated user's organization into the cache.
User Story
Acceptance Criteria
- Given a feature flag is disabled for my organization, when a peer mentor in my organization opens the app, then the UI sections and navigation tabs guarded by that flag are not rendered or accessible
- Given a feature flag is enabled for my organization, when any user in my organization opens the app, then the guarded UI elements are visible and functional
- Given the feature-flag-initializer runs on app startup, when the user is authenticated, then all feature flags for their organization are pre-loaded into the feature-flag-cache within 2 seconds
- Given flags are cached, when the feature-gate-widget evaluates a flag, then the evaluation is synchronous and does not cause a visible loading delay or layout shift
- Given a flag is toggled by an administrator, when an active user's session receives the updated flag state, then the UI reflects the change within one app foreground cycle (on next resume or navigation)
- Given a user belongs to an organization with no explicit flag configuration for a given flag, when the rollout-evaluator is consulted, then the flag defaults to its defined default state from feature-flag-constants
Business Value
Runtime feature gating is the foundational mechanism enabling the parallel-systems transition strategy all organizations require. By hiding incomplete or organization-irrelevant features (e.g., driver honorarium for NHF which does not need it), the app stays simple and low-cognitive-load for each organization's volunteers. This is directly linked to the #1 design principle: lowest possible cognitive load.
Components
- FeatureGate Widget ui
- Feature Flag Provider infrastructure
- Rollout Condition Evaluator service
- Feature Flag Local Cache data
- Feature Flag Key Constants infrastructure
- Feature Flag Initializer infrastructure
- Feature Flag Repository data