Activity Repository
Component Detail
Description
Data access layer for activity records, providing CRUD operations against the Supabase activities table. Implements an optimistic insert pattern that returns an ActivityRecord with a temporary local ID immediately, later reconciling the server-assigned ID on async confirmation.
activity-repository
Summaries
The Activity Repository ensures that peer mentors can log activities instantly without waiting for network confirmation, eliminating frustrating delays and preventing data loss in low-connectivity environments. By adopting an optimistic insert pattern, the app feels fast and reliable even on poor mobile networks — directly improving mentor satisfaction and compliance rates. Every logged activity is a billable or reportable data point; losing records due to connectivity issues represents real revenue risk and compliance exposure. This component safeguards that data with automatic retry queuing, protecting the organisation's audit trail and reducing the risk of regulatory or contractual penalties stemming from incomplete activity records.
The Activity Repository is a medium-complexity data layer component that underpins all activity logging flows. It has a single upstream dependency on the Supabase Activity Client, meaning any delays in finalising the Supabase schema or RLS policies will block or require rework of this component. The optimistic insert pattern introduces a local ID reconciliation step that must be thoroughly tested — particularly edge cases around network failures mid-insert and app restarts before confirmation arrives. QA should budget time for offline/flaky-network simulation tests.
Deployment requires that the Supabase activities table and associated policies are stable before release; plan a joint integration test milestone with the backend team.
Activity Repository implements the repository pattern as the sole data access point for the activities Supabase table. Its central design decision is the optimistic insert: `insertOptimistic()` generates a temporary local UUID, writes the record to a local pending queue, and returns immediately to the caller so the UI can proceed without blocking. A background process then calls Supabase, and `confirmInsert(localId, remoteId)` replaces the local ID with the server-assigned UUID across all in-memory and persisted references. Failure paths must handle HTTP 4xx (validation), 5xx (server error), and network timeouts separately — transient errors should re-queue, permanent errors should surface to the UI.
`getByPeerMentor()` supports optional date-range filtering passed directly as Supabase query predicates. Depends solely on `supabase-activity-client`; avoid leaking Supabase types through this boundary — map to internal `ActivityRecord` DTOs at this layer.
Responsibilities
- Insert new activity records into Supabase with optimistic local ID
- Fetch activity records filtered by peer mentor ID and organisation
- Update records after server confirmation to replace local IDs
- Handle network errors and queue failed inserts for retry
Interfaces
insertOptimistic(ActivityRecord record) -> ActivityRecord
confirmInsert(String localId, String remoteId)
getByPeerMentor(String mentorId, {DateTime? from, DateTime? to}) -> Future<List<ActivityRecord>>
getById(String id) -> Future<ActivityRecord?>
update(ActivityRecord record) -> Future<ActivityRecord>
delete(String id) -> Future<void>
Relationships
Dependencies (1)
Components this component depends on
Used Integrations (1)
External integrations and APIs this component relies on