Terminology Repository
Component Detail
Description
Data-layer abstraction for fetching and persisting organization terminology maps. Queries the organization_configs Supabase table for the labels JSONB column, deserializes it into a typed Dart map, and delegates offline reads to the local cache adapter. Hides the Supabase client from higher-level services.
terminology-repository
Summaries
The Terminology Repository is the authoritative data gateway that connects the app to each organization's custom label configuration stored in the cloud. It ensures the app always presents terminology that matches what the organization has configured in the backend, with no manual intervention required. By abstracting the database access layer, it insulates the business logic from infrastructure changes—if the backend storage technology or schema changes, only this component needs updating, protecting the rest of the product from costly cascading changes. Its offline fallback delegation also ensures continuity of service in low-connectivity field environments.
This is a low-complexity data-layer component but it is a foundational dependency for both the Terminology Sync Service and the OrganizationLabelsNotifier, so it should be prioritized early in the delivery roadmap. It depends only on the Cache Adapter and the Supabase client configuration, both of which are infrastructure-level concerns. The main scheduling risk is Supabase schema availability—ensure the `organization_configs` table with its `labels` JSONB column and `updated_at` field is confirmed and accessible in the development environment before this component enters implementation. Integration tests require a seeded Supabase instance with multi-org test data.
Wraps the Supabase PostgREST client to query `organization_configs` for the `labels` JSONB column and `updated_at` field. `fetchLabels(organizationId)` deserializes the JSONB payload into `Map
Offline reads are delegated to `terminology-cache-adapter.read()` when a `SocketException` or `PostgrestException` is caught. Supabase client injection via the Riverpod provider graph keeps this testable with a mock client.
Responsibilities
- Fetch the labels JSONB column from organization_configs for a given organization ID
- Deserialize JSONB into Map<String, String> with type safety
- Delegate reads to local cache when network is unavailable
- Return the server-side updated_at timestamp for version comparison
Interfaces
fetchLabels(organizationId) → Future<Map<String, String>>
fetchUpdatedAt(organizationId) → Future<DateTime>
fetchAll() → Future<Map<String, Map<String, String>>>
watchLabels(organizationId) → Stream<Map<String, String>>
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component