Supabase Activity Client
Component Detail
Description
Low-level Supabase client wrapper scoped to the activities table. Abstracts PostgREST query construction and error mapping, providing a typed interface consumed by ActivityRepository and ensuring all Supabase interactions are centralised and testable.
supabase-activity-client
Summaries
The Supabase Activity Client is a critical data reliability layer that protects the business from data integrity failures and inconsistent user experiences. By centralising all interactions with the activities database into a single, controlled access point, it eliminates the risk of scattered, unvalidated database calls that could expose sensitive user data or corrupt records. This directly reduces the risk of costly data incidents, supports regulatory compliance through enforced row-level security, and ensures that every user sees accurate, authorised data — building long-term trust and reducing support overhead. Its shared, reusable design also means lower development costs across all features that rely on activity data.
This component is a low-complexity shared infrastructure piece that underpins all activity-related features. Because it centralises Supabase interactions, it must be completed and stabilised before any feature team can build reliable data persistence. This creates a hard scheduling dependency — teams building activity logging, retrieval, or editing features are blocked until this client is stable and tested. The upside is that its isolated, well-defined scope makes it straightforward to unit test in isolation.
Key delivery risks include Supabase API changes or network timeout behaviour that may surface late. Allocate time for integration testing with real Supabase environments, not just mocks, to catch row-level security edge cases early.
The Supabase Activity Client is a thin but essential wrapper around the Supabase PostgREST SDK, scoped exclusively to the activities table. It exposes typed async methods — insert, select, update, delete — with structured filter support, and maps all Supabase-specific error codes to domain-level exceptions via mapSupabaseError(), decoupling upstream consumers from SDK internals. It applies the authenticated session's row-level security context automatically, ensuring queries are always user-scoped. Consumed by ActivityRepository as its sole data source.
Because it has no dependencies itself, it is the lowest layer in the data stack and should be the primary target for integration tests against a real or emulated Supabase instance. Request timeout enforcement is built in, so callers do not need defensive wrapping.
Responsibilities
- Execute typed PostgREST insert, select, update, and delete queries on the activities table
- Map Supabase error codes to domain-level exceptions
- Apply row-level security context from the current authenticated session
- Enforce request timeouts and surface network errors
Interfaces
insert(Map<String, dynamic> data) -> Future<Map<String, dynamic>>
select(String query, {Map<String, dynamic>? filters}) -> Future<List<Map<String, dynamic>>>
update(String id, Map<String, dynamic> data) -> Future<Map<String, dynamic>>
delete(String id) -> Future<void>
mapSupabaseError(Object error) -> DomainException