Organization Labels Notifier
Component Detail
Description
A Riverpod StateNotifier that manages the active organization's terminology map lifecycle. On login it fetches the JSONB terminology map from the organization_configs Supabase table, writes it to local cache, and exposes a label(key) helper consumed throughout the widget tree. Reactively updates when the authenticated organization changes.
organization-labels-notifier
Summaries
The Organization Labels Notifier is the engine behind the app's white-label and multi-tenant branding capability. Every organization can use its own terminology—renaming roles, actions, or entities to match its internal culture—without requiring a separate app build. This dramatically reduces the cost of onboarding new enterprise clients, eliminates the need for custom builds, and allows sales to close multi-tenant deals with confidence. By caching labels locally, users see correct terminology immediately on launch, reinforcing brand trust and reducing confusion-driven support tickets across the customer base.
This is a shared, medium-complexity mobile component that underpins terminology customization across the entire widget tree. It must be completed before any feature that displays organization-specific labels, making it an early-sprint dependency. It depends on the Terminology Repository and Cache Adapter, so those two components must be delivered first. Testing requires multi-org fixture data in Supabase and offline/online scenario coverage.
The reactive update on organization switch adds integration test complexity. Plan for at least one sprint to stabilize edge cases around login timing and organization context transitions.
Implemented as a Riverpod StateNotifier, this component manages the full lifecycle of a per-organization terminology map. On login and organization switch it calls `loadForOrganization(organizationId)`, which fetches from the Terminology Repository, writes to the Cache Adapter, and exposes the map reactively. The `label(key)` helper is the primary consumer API used across the widget tree. The notifier delegates cache reads and writes to `terminology-cache-adapter` and network fetches to `terminology-repository`.
Watch for race conditions when organizations switch mid-session; invalidation logic must be atomic. The `missingKeys()` interface supports development-time auditing of terminology coverage.
Responsibilities
- Fetch terminology map from Supabase on login and organization switch
- Expose a label(key) helper that resolves keys to organization-specific strings
- Write fetched map to local cache for offline availability
- Invalidate and refresh map when organization context changes
Interfaces
label(String key) → String
labelOrNull(String key) → String?
loadForOrganization(organizationId)
refresh()
hasCachedMap(organizationId) → bool
clearCache()
getFullMap() → Map<String, String>
missingKeys() → List<String>
Relationships
Dependencies (2)
Components this component depends on
Dependents (4)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component