Organization Labels & Terminology
Feature Detail
Description
Different member organizations use different terminology for the same concepts: what NHF calls a 'likeperson' may be called something different by Blindeforbundet or HLF, and role names, activity types, and organizational unit names vary across clients. This feature provides a dynamic label configuration system that allows each organization to define their own terminology, which is then applied globally throughout the app UI. Labels are loaded at startup and injected into all UI strings, ensuring that each organization sees language that matches their internal culture and documentation.
Analysis
Terminology consistency between the app and an organization's existing culture and documentation is a significant adoption factor. When volunteers and coordinators encounter unfamiliar labels for familiar concepts, cognitive friction increases and trust in the tool decreases. By allowing organizations to configure their own labels, Norse Digital Products dramatically reduces this friction and enables faster onboarding. This also future-proofs the product for new organizational clients with different conventions, reducing the need for custom development per client. The system supports NHF's noted interest in eventual Sami language support, as the label system can accommodate locale-specific overrides.
The Labels Service fetches the active organization's label configuration from Supabase on app startup and caches it in the Riverpod state layer. The Dynamic Label Widget is a utility widget that accepts a label key and renders the organization-specific string, falling back to a default value if no custom label is configured. The Labels Config Screen in the admin portal presents a form-based editor for all configurable label keys. Label keys and defaults are defined in a Dart constants file to ensure type safety and prevent typos. The implementation should support at minimum: role names, organizational unit names, activity type labels, and report terminology. Consider using Flutter's existing l10n infrastructure as the underlying mechanism for label injection.
Dependencies
Definition of Done
Components (5)
User Stories (8)
As a As an administrator
I want I want to reset individual label keys or the entire label configuration back to the system defaults defined in the Label Keys Constants
So that So that I can undo customizations that are no longer appropriate or recover from a misconfigured label without manually re-entering default strings
- Given the labels config screen is open, when an administrator clicks the reset control on an individual label key, then that key's input field is repopulated with the system default from Label Keys Constants
- Given the labels config screen is open, when an administrator uses the bulk reset action and confirms, then all label keys are restored to their system defaults and the change is saved to the Labels Repository
- Given a label key has been reset to default, when the Dynamic Label Widget renders that key, then the system default string from Label Keys Constants is displayed
- +1 more
As a As an administrator
I want I want to see the complete list of all configurable label keys with their current organization-specific values and the system default for each key displayed side by side
So that So that I have a clear reference of what terminology can be customized and can make informed decisions about which labels to change without needing to guess what each key controls
- Given an administrator opens the Labels Config screen, when the screen loads, then all label keys from the Label Keys Constants file are displayed, organized into logical category groups
- Given the labels list is displayed, when an administrator views any row, then both the system default value and the current custom value (or empty state indicating default is in use) are visible for that key
- Given an organization has no custom labels configured, when an administrator opens the Labels Config screen for the first time, then all keys show their system default values as reference and the fields are clearly indicated as using defaults
- +1 more
As a As an administrator
I want I want to reset individual label keys or the entire label configuration back to the system defaults defined in the Label Keys Constants
So that So that I can undo customizations that are no longer appropriate or recover from a misconfigured label without manually re-entering default strings
- Given the labels config screen is open, when an administrator clicks the reset control on an individual label key, then that key's input field is repopulated with the system default from Label Keys Constants
- Given the labels config screen is open, when an administrator uses the bulk reset action and confirms, then all label keys are restored to their system defaults and the change is saved to the Labels Repository
- Given a label key has been reset to default, when the Dynamic Label Widget renders that key, then the system default string from Label Keys Constants is displayed
- +1 more
As a As an administrator
I want I want to see the complete list of all configurable label keys with their current organization-specific values and the system default for each key displayed side by side
So that So that I have a clear reference of what terminology can be customized and can make informed decisions about which labels to change without needing to guess what each key controls
- Given an administrator opens the Labels Config screen, when the screen loads, then all label keys from the Label Keys Constants file are displayed, organized into logical category groups
- Given the labels list is displayed, when an administrator views any row, then both the system default value and the current custom value (or empty state indicating default is in use) are visible for that key
- Given an organization has no custom labels configured, when an administrator opens the Labels Config screen for the first time, then all keys show their system default values as reference and the fields are clearly indicated as using defaults
- +1 more
As a As a Global Administrator
I want I want to access and configure the labels for any organization context during platform onboarding, setting their initial terminology before the first users log in
So that So that newly onboarded organizations see their own terminology from the very first session, avoiding a period where volunteers encounter unfamiliar default labels that create confusion and erode trust
- Given a global administrator has selected a specific organization context in the admin portal, when they open the Labels Config screen, then the labels displayed and edited are scoped to the selected organization
- Given a global administrator saves labels for an organization, when a user from that organization logs in for the first time, then the app loads the pre-configured terminology set on startup
- Given a global administrator has configured labels for an organization, when the organization's own administrator later opens the Labels Config screen, then they see the pre-configured values and can further refine them
- +1 more
As a As a Organization Administrator
I want I want to edit multiple terminology labels across all categories in a single editing session and save the entire configuration with one action
So that So that I can set up or revise my organization's full terminology set in one go without losing partial changes or needing to save each label individually
- Given an administrator is on the Labels Config screen, when they modify multiple label fields across different categories, then all changes are held in local form state until explicitly saved
- Given unsaved changes exist, when the administrator taps Save Configuration, then all modified labels are written to the org_labels table in a single batch operation
- Given a batch save completes successfully, when the Labels Service is queried, then it returns the newly saved values for all updated keys
- +2 more
As a As an administrator
I want I want to open the labels configuration screen and edit the terminology strings for all configurable label keys — including role names, organizational unit names, activity type labels, and report terminology — to match my organization's internal language
So that So that all volunteers, coordinators, and staff see language in the app that matches the documentation, training materials, and culture they already know, reducing cognitive friction and increasing adoption
- Given an administrator navigates to the admin portal, when they open the Labels Config screen, then all configurable label keys are listed with their current values and system defaults visible side by side
- Given the labels config screen is open, when an administrator edits one or more label fields and taps Save, then all changes are batch-written to the org_labels table via the Labels Repository
- Given a label has been saved, when any user opens or navigates within the app, then the Dynamic Label Widget renders the organization-specific string for that key everywhere it appears
- +2 more
As a As an administrator
I want I want to open the labels configuration screen and edit the terminology strings for all configurable label keys — including role names, organizational unit names, activity type labels, and report terminology — to match my organization's internal language
So that So that all volunteers, coordinators, and staff see language in the app that matches the documentation, training materials, and culture they already know, reducing cognitive friction and increasing adoption
- Given an administrator navigates to the admin portal, when they open the Labels Config screen, then all configurable label keys are listed with their current values and system defaults visible side by side
- Given the labels config screen is open, when an administrator edits one or more label fields and taps Save, then all changes are batch-written to the org_labels table via the Labels Repository
- Given a label has been saved, when any user opens or navigates within the app, then the Dynamic Label Widget renders the organization-specific string for that key everywhere it appears
- +2 more