Organization Repository
Component Detail
Description
Data access layer responsible for fetching, caching, and exposing organization records from Supabase. Provides the complete list of active partner organizations and shallow org-profile data needed for selection validation. Implements local cache to avoid redundant network calls within a session.
organization-repository
Summaries
The Organization Repository serves as the single authoritative source for partner organization data within the mobile application, ensuring that all screens displaying organization names, profiles, and selection options are reading from a consistent, validated dataset. By implementing a session-level cache, it eliminates redundant network calls that would otherwise increase API costs, degrade performance on slow connections, and frustrate users during the critical onboarding moment of organization selection. As a shared component used across multiple features, it delivers compounding value: every feature that needs org data benefits from its caching and validation logic without duplicating that complexity. This directly reduces development cost and the risk of data inconsistency errors that could undermine user trust in the platform.
The Organization Repository is a medium-complexity shared data component with a dependency on the secure-storage-adapter, which must be available before integration work begins. As a shared component, it sits on the critical path for several downstream features — any delay or API contract change here will ripple across the organization selection screen, the multi-org resolver, and any other feature consuming org data. Testing requirements include unit tests for cache hit/miss behavior, mock-based integration tests against the Supabase data layer, and stream emission tests for the reactive `watchOrganizations()` interface. Plan for a cache invalidation strategy review with the team, as premature or missing invalidation calls are a common source of stale-data bugs in session-cached repositories.
Allocate time for schema alignment with the backend team to ensure Supabase organization table columns map cleanly to the `Organization` domain model.
The Organization Repository implements the repository pattern as a data access layer over Supabase, mapping raw database rows to strongly typed `Organization` and `OrgProfile` domain models. It exposes both one-shot futures (`getAllActiveOrganizations`, `getOrganizationById`, `getOrgProfile`) and a reactive stream (`watchOrganizations`) backed by Supabase's real-time subscription capability, allowing the UI to respond to org list changes without polling. The in-memory session cache should be implemented as a simple `Map
Key architectural note: because this is a shared component, it should be registered as a singleton in the DI container (e.g., Riverpod `Provider` at root scope) to ensure all consumers share the same cache instance. Avoid making the cache Hive/SQLite-backed unless offline-first is an explicit requirement — in-memory is sufficient for session scope.
Responsibilities
- Fetch all active organizations from Supabase
- Fetch a single org profile by ID for validation
- Cache org list in memory for the session
- Map Supabase rows to typed Organization domain models
- Expose stream for reactive org list updates
Interfaces
getAllActiveOrganizations() -> Future<List<Organization>>
getOrganizationById(String orgId) -> Future<Organization?>
getOrgProfile(String orgId) -> Future<OrgProfile>
watchOrganizations() -> Stream<List<Organization>>
invalidateCache() -> void
Relationships
Dependents (3)
Components that depend on this component