Feature flags initialize correctly on app startup for offline resilience
The feature-flag-initializer fetches the full flag configuration for the authenticated user's organization on startup and stores it in the feature-flag-cache. If the network is unavailable at startup, the initializer falls back to the last successfully cached flag set stored in local persistent storage. The cache TTL is configurable via feature-flag-constants and defaults to 24 hours for offline resilience. When connectivity is restored, a background refresh updates the cache without disrupting the active session. A stale-cache indicator should be shown in the admin screen if flags were last synced more than the TTL period ago.
User Story
Acceptance Criteria
- 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
- Given the network is restored after an offline period, when the app returns to the foreground, then a background refresh of flags is triggered and the cache is updated silently
- Given the cached flags are older than the configured TTL, when the administrator views the feature flag admin screen, then a stale-cache warning is displayed with the last-synced timestamp
- Given feature-flag-constants defines a default state for each flag, when no cached data exists and no network is available, then the flag defaults to the defined constant value rather than crashing
Business Value
Peer mentors frequently conduct home visits in locations with unreliable mobile coverage. If feature flags reset to defaults during an offline session, the app could hide active features (like activity registration) or show disabled ones, directly disrupting reporting workflows. Offline resilience for flag state is essential to the reliability promise made to all three organizations and directly supports the core activity registration use case rated as #1 priority by every organization.
Components
- Feature Flag Initializer infrastructure
- Feature Flag Local Cache data
- Feature Flag Provider infrastructure
- Feature Flag Repository data
- Feature Flag Key Constants infrastructure
- FeatureGate Widget ui