Label Key Resolver Service
Component Detail
Description
Stateless utility service that applies resolution logic to raw terminology maps: handles missing keys with fallbacks, supports parameterized labels (e.g., role name interpolation), and enforces a consistent key naming convention across the codebase. Used internally by OrganizationLabelsNotifier and directly in non-widget contexts such as notification payload generation.
label-key-resolver
Summaries
The Label Key Resolver ensures that every piece of user-facing text is consistently derived from the organization's custom terminology, even in non-visual contexts like push notifications and background processing. By standardizing how labels are looked up and providing safe English fallbacks, it eliminates the risk of raw technical keys appearing in user-facing messages—protecting brand quality across all touchpoints. Its shared execution context means the same logic governs both the mobile UI and server-side notification payloads, ensuring messaging coherence that strengthens user trust and reduces brand inconsistency complaints.
This is a low-complexity, stateless utility with no external dependencies, making it one of the safest and fastest components to deliver. It should be completed early since both the OrganizationLabelsNotifier and notification services depend on it. There are no network, database, or platform dependencies to coordinate. Testing is straightforward: unit tests covering key resolution, parameterized interpolation, fallback behavior, and key convention validation are sufficient.
The main delivery risk is agreeing on the key naming convention before other teams start generating keys—document the convention in the sprint and enforce it via `validateKeyConvention()` from day one.
A pure stateless service with no Riverpod or Flutter dependencies, making it usable in Dart-only contexts such as background isolates and notification payload builders. The core API is `resolve(key, map, {params})`, which looks up a key, applies `interpolate(template, params)` for parameterized substitution, and falls back to `resolveWithFallback` if the key is absent. `buildDefaultFallbackMap()` provides a hardcoded English map for organizations with incomplete configurations. `validateKeyConvention(key)` enforces a naming standard (e.g., snake_case with namespace prefixes) and should be wired into CI linting.
No state is held between calls; all inputs are explicit, making the service trivially testable and safe to call from any isolate.
Responsibilities
- Resolve a label key against a given terminology map with fallback logic
- Support parameterized substitution in label strings
- Validate key naming conventions and report violations
- Provide a default English fallback map for unknown organizations
Interfaces
resolve(key, map, {params}) → String
resolveWithFallback(key, map, fallback) → String
validateKeyConvention(key) → bool
buildDefaultFallbackMap() → Map<String, String>
interpolate(template, params) → String
Relationships
Dependents (1)
Components that depend on this component
Related Data Entities (1)
Data entities managed by this component