Organization-scoped Feature Flags
Feature Detail
Description
Different organizations require different feature sets: travel reimbursement is needed by HLF and Blindeforbundet but not NHF; course administration and certification is HLF-specific; encrypted assignment dispatch is Blindeforbundet-specific; gamification is relevant to NHF and HLF but not Blindeforbundet. This feature provides a per-organization feature flag configuration that controls which screens, tabs, form fields, and menu items are visible or active for each tenant. Flags are evaluated at runtime from a Supabase-backed configuration table and surfaced via a provider so any widget can gate its rendering on a single boolean check. The flag system also supports phase-based rollout — a feature can be enabled for an organization only from a specific app version or date, enabling the incremental rollout strategy all organizations explicitly require.
Analysis
Allows the product team to ship a single app that precisely matches each organization's contracted feature set without custom builds. It also de-risks new feature launches by enabling per-org gradual rollout, directly addressing the 'parallel systems during transition' requirement raised by all three workshop organizations.
Model flags as a flat key-value map in `organization_configs` (e.g., `features.travel_reimbursement: true`). Expose via a `FeatureFlagProvider` in Riverpod. Use a `FeatureGate` widget wrapper for conditional rendering rather than scattering `if` statements. Cache flags locally with a short TTL. Ensure BLoC/Cubit state machines for feature-heavy flows also consult flags at initialization to avoid partially rendered states.
Components (203)
Shared Components
These components are reused across multiple features
User Interface (59)
Service Layer (52)
Data Layer (33)
Infrastructure (54)
User Stories (21)
As a As a Peer Mentor (Likeperson)
I want to view a history of all feature flag changes made within my organization, including who made the change and when
So that I can understand the timeline of feature activations, diagnose unexpected behavior reported by peer mentors, and maintain accountability for configuration decisions
- Given I am on the feature flag admin screen, when I navigate to the audit log section, then I see a chronologically ordered list of all flag change events for my organization
- Given the audit log is displayed, when I view an entry, then I can see the flag name, old state, new state, changed-by administrator name, and timestamp
- Given the audit log has more than 20 entries, when I scroll to the bottom of the visible list, then older entries are loaded via pagination
- +3 more
As a As a Peer Mentor (Likeperson)
I want to enable a feature for a percentage of users in my organization before full rollout
So that I can test new features like gamification or scenario-based notifications with a small subset of peer mentors before exposing them to the entire organization, reducing the risk of disruption
- Given I am on the feature flag admin screen, when I open the configuration for a flag, then I can set a rollout percentage between 0 and 100
- Given I set a rollout percentage of 20%, when the rollout-evaluator determines feature visibility for a user, then approximately 20% of users in my organization consistently see the feature enabled
- Given a user is assigned to the enabled cohort at 20% rollout, when the percentage is later increased to 50%, then that user remains in the enabled cohort (deterministic assignment)
- +3 more
As a As a Coordinator
I want to view a history of all feature flag changes made within my organization, including who made the change and when
So that I can understand the timeline of feature activations, diagnose unexpected behavior reported by peer mentors, and maintain accountability for configuration decisions
- Given I am on the feature flag admin screen, when I navigate to the audit log section, then I see a chronologically ordered list of all flag change events for my organization
- Given the audit log is displayed, when I view an entry, then I can see the flag name, old state, new state, changed-by administrator name, and timestamp
- Given the audit log has more than 20 entries, when I scroll to the bottom of the visible list, then older entries are loaded via pagination
- +3 more
As a As a Coordinator
I want to enable a feature for a percentage of users in my organization before full rollout
So that I can test new features like gamification or scenario-based notifications with a small subset of peer mentors before exposing them to the entire organization, reducing the risk of disruption
- Given I am on the feature flag admin screen, when I open the configuration for a flag, then I can set a rollout percentage between 0 and 100
- Given I set a rollout percentage of 20%, when the rollout-evaluator determines feature visibility for a user, then approximately 20% of users in my organization consistently see the feature enabled
- Given a user is assigned to the enabled cohort at 20% rollout, when the percentage is later increased to 50%, then that user remains in the enabled cohort (deterministic assignment)
- +3 more
As a As an Organization Administrator
I want to view a history of all feature flag changes made within my organization, including who made the change and when
So that I can understand the timeline of feature activations, diagnose unexpected behavior reported by peer mentors, and maintain accountability for configuration decisions
- Given I am on the feature flag admin screen, when I navigate to the audit log section, then I see a chronologically ordered list of all flag change events for my organization
- Given the audit log is displayed, when I view an entry, then I can see the flag name, old state, new state, changed-by administrator name, and timestamp
- Given the audit log has more than 20 entries, when I scroll to the bottom of the visible list, then older entries are loaded via pagination
- +3 more
As a As an Organization Administrator
I want to enable a feature for a percentage of users in my organization before full rollout
So that I can test new features like gamification or scenario-based notifications with a small subset of peer mentors before exposing them to the entire organization, reducing the risk of disruption
- Given I am on the feature flag admin screen, when I open the configuration for a flag, then I can set a rollout percentage between 0 and 100
- Given I set a rollout percentage of 20%, when the rollout-evaluator determines feature visibility for a user, then approximately 20% of users in my organization consistently see the feature enabled
- Given a user is assigned to the enabled cohort at 20% rollout, when the percentage is later increased to 50%, then that user remains in the enabled cohort (deterministic assignment)
- +3 more
As a As a Peer Mentor (Likeperson)
I want to view a dashboard of all available feature flags and their current enabled/disabled state for my organization
So that I can understand which capabilities are active for my peer mentors and coordinators, and make informed decisions about enabling new features
- Given I am logged in as an organization administrator, when I navigate to the feature flag admin screen, then I see a list of all feature flags applicable to my organization
- Given the feature flag list is displayed, when I view each flag entry, then I can see the flag name, human-readable description, current enabled/disabled state, and last modified timestamp
- Given I view the feature flags screen, when data is loading from the repository, then a loading indicator is shown and the list renders completely before interaction is possible
- +2 more
As a As a Peer Mentor (Likeperson)
I want to toggle individual feature flags on or off for my organization with a confirmation step
So that I can safely activate or deactivate capabilities such as driver honorarium, mileage reimbursement, or proxy registration without risking accidental changes
- Given I am viewing the feature flag admin screen, when I tap the toggle for a flag, then a confirmation dialog appears showing the flag name, the proposed new state, and a plain-language description of the impact
- Given the confirmation dialog is shown, when I confirm the change, then the flag state is updated in the repository and the feature-flag-cache is invalidated
- Given I confirm enabling a flag, when the update succeeds, then a success toast is shown and the toggle reflects the new enabled state immediately
- +3 more
As a As a Peer Mentor (Likeperson)
I want feature flags to be cached locally after the first successful load so that the app continues to function correctly when the device is temporarily offline
So that peer mentors in areas with poor connectivity (e.g., rural home visits) do not lose access to enabled features or suddenly see disabled features reappear due to a failed flag fetch
- Given the app starts with a valid network connection, when the feature-flag-initializer runs, then all flags for the authenticated organization are fetched and stored in the feature-flag-cache within 2 seconds
- Given the app starts with no network connection, when the feature-flag-initializer runs, then the last cached flag set is loaded from local persistent storage and used without error
- Given the device goes offline after startup, when a feature-gate-widget evaluates a flag, then it uses the cached values and the UI does not change or hide previously visible features
- +3 more
As a As a Coordinator
I want to view a dashboard of all available feature flags and their current enabled/disabled state for my organization
So that I can understand which capabilities are active for my peer mentors and coordinators, and make informed decisions about enabling new features
- Given I am logged in as an organization administrator, when I navigate to the feature flag admin screen, then I see a list of all feature flags applicable to my organization
- Given the feature flag list is displayed, when I view each flag entry, then I can see the flag name, human-readable description, current enabled/disabled state, and last modified timestamp
- Given I view the feature flags screen, when data is loading from the repository, then a loading indicator is shown and the list renders completely before interaction is possible
- +2 more
As a As a Coordinator
I want to toggle individual feature flags on or off for my organization with a confirmation step
So that I can safely activate or deactivate capabilities such as driver honorarium, mileage reimbursement, or proxy registration without risking accidental changes
- Given I am viewing the feature flag admin screen, when I tap the toggle for a flag, then a confirmation dialog appears showing the flag name, the proposed new state, and a plain-language description of the impact
- Given the confirmation dialog is shown, when I confirm the change, then the flag state is updated in the repository and the feature-flag-cache is invalidated
- Given I confirm enabling a flag, when the update succeeds, then a success toast is shown and the toggle reflects the new enabled state immediately
- +3 more
As a As a Coordinator
I want feature flags to be cached locally after the first successful load so that the app continues to function correctly when the device is temporarily offline
So that peer mentors in areas with poor connectivity (e.g., rural home visits) do not lose access to enabled features or suddenly see disabled features reappear due to a failed flag fetch
- Given the app starts with a valid network connection, when the feature-flag-initializer runs, then all flags for the authenticated organization are fetched and stored in the feature-flag-cache within 2 seconds
- Given the app starts with no network connection, when the feature-flag-initializer runs, then the last cached flag set is loaded from local persistent storage and used without error
- Given the device goes offline after startup, when a feature-gate-widget evaluates a flag, then it uses the cached values and the UI does not change or hide previously visible features
- +3 more
As a As an Organization Administrator
I want to view a dashboard of all available feature flags and their current enabled/disabled state for my organization
So that I can understand which capabilities are active for my peer mentors and coordinators, and make informed decisions about enabling new features
- Given I am logged in as an organization administrator, when I navigate to the feature flag admin screen, then I see a list of all feature flags applicable to my organization
- Given the feature flag list is displayed, when I view each flag entry, then I can see the flag name, human-readable description, current enabled/disabled state, and last modified timestamp
- Given I view the feature flags screen, when data is loading from the repository, then a loading indicator is shown and the list renders completely before interaction is possible
- +2 more
As a As an Organization Administrator
I want to toggle individual feature flags on or off for my organization with a confirmation step
So that I can safely activate or deactivate capabilities such as driver honorarium, mileage reimbursement, or proxy registration without risking accidental changes
- Given I am viewing the feature flag admin screen, when I tap the toggle for a flag, then a confirmation dialog appears showing the flag name, the proposed new state, and a plain-language description of the impact
- Given the confirmation dialog is shown, when I confirm the change, then the flag state is updated in the repository and the feature-flag-cache is invalidated
- Given I confirm enabling a flag, when the update succeeds, then a success toast is shown and the toggle reflects the new enabled state immediately
- +3 more
As a As an Organization Administrator
I want feature flags to be cached locally after the first successful load so that the app continues to function correctly when the device is temporarily offline
So that peer mentors in areas with poor connectivity (e.g., rural home visits) do not lose access to enabled features or suddenly see disabled features reappear due to a failed flag fetch
- Given the app starts with a valid network connection, when the feature-flag-initializer runs, then all flags for the authenticated organization are fetched and stored in the feature-flag-cache within 2 seconds
- Given the app starts with no network connection, when the feature-flag-initializer runs, then the last cached flag set is loaded from local persistent storage and used without error
- Given the device goes offline after startup, when a feature-gate-widget evaluates a flag, then it uses the cached values and the UI does not change or hide previously visible features
- +3 more
As a As a Peer Mentor (Likeperson)
I want feature flags to be evaluated at runtime so that UI elements and navigation routes are automatically shown or hidden based on my organization's configuration
So that peer mentors and coordinators in my organization only see the features that are enabled and relevant for us, reducing cognitive load and preventing access to unfinished capabilities
- 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
- +3 more
As a As a Peer Mentor (Likeperson)
I want feature flag configurations to be strictly isolated per organization so that my flag settings never affect or are visible to other organizations
So that sensitive capability decisions (e.g., enabling encrypted assignment handling or driver honorarium) remain private to my organization and cannot be inadvertently applied organization-wide
- Given user A belongs to Organization A and user B belongs to Organization B, when Organization A enables a feature flag, then the flag remains disabled for Organization B unless separately configured
- Given the feature-flag-repository executes a read query, when inspecting the generated SQL, then an organization_id filter is always present in the WHERE clause
- Given the feature-flag-cache stores a flag value, when the cache key is inspected, then it includes both the organization_id and the flag_key
- +3 more
As a As a Coordinator
I want feature flags to be evaluated at runtime so that UI elements and navigation routes are automatically shown or hidden based on my organization's configuration
So that peer mentors and coordinators in my organization only see the features that are enabled and relevant for us, reducing cognitive load and preventing access to unfinished capabilities
- 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
- +3 more
As a As a Coordinator
I want feature flag configurations to be strictly isolated per organization so that my flag settings never affect or are visible to other organizations
So that sensitive capability decisions (e.g., enabling encrypted assignment handling or driver honorarium) remain private to my organization and cannot be inadvertently applied organization-wide
- Given user A belongs to Organization A and user B belongs to Organization B, when Organization A enables a feature flag, then the flag remains disabled for Organization B unless separately configured
- Given the feature-flag-repository executes a read query, when inspecting the generated SQL, then an organization_id filter is always present in the WHERE clause
- Given the feature-flag-cache stores a flag value, when the cache key is inspected, then it includes both the organization_id and the flag_key
- +3 more
As a As an Organization Administrator
I want feature flags to be evaluated at runtime so that UI elements and navigation routes are automatically shown or hidden based on my organization's configuration
So that peer mentors and coordinators in my organization only see the features that are enabled and relevant for us, reducing cognitive load and preventing access to unfinished capabilities
- 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
- +3 more
As a As an Organization Administrator
I want feature flag configurations to be strictly isolated per organization so that my flag settings never affect or are visible to other organizations
So that sensitive capability decisions (e.g., enabling encrypted assignment handling or driver honorarium) remain private to my organization and cannot be inadvertently applied organization-wide
- Given user A belongs to Organization A and user B belongs to Organization B, when Organization A enables a feature flag, then the flag remains disabled for Organization B unless separately configured
- Given the feature-flag-repository executes a read query, when inspecting the generated SQL, then an organization_id filter is always present in the WHERE clause
- Given the feature-flag-cache stores a flag value, when the cache key is inspected, then it includes both the organization_id and the flag_key
- +3 more