Annual Summary Repository
Component Detail
Description
Data access layer that queries Supabase for a peer mentor's activity records within a specified date range, transforming raw database rows into domain-level aggregated stats models. Abstracts both the remote Supabase source and the local offline cache behind a single interface.
annual-summary-repository
Summaries
The Annual Summary Repository is the data foundation that makes the entire peer mentor recognition experience possible. It retrieves and structures each mentor's activity history from the platform's Supabase backend, transforming raw records into the meaningful aggregated statistics that power milestone detection, impact visualisations, and personalised summaries. By abstracting both online and offline data access behind a single consistent interface, the repository ensures mentors experience fast, reliable summary loading regardless of their network conditions — a critical quality signal in markets where connectivity is inconsistent. Reliable data access at this layer directly protects the platform's reputation for accuracy and trustworthiness, which is foundational to mentor confidence and continued engagement.
The Annual Summary Repository is a medium-complexity component that is a hard dependency for both the Milestone Detection Service and the Wrapped Summary BLoC, meaning delays in its delivery will block downstream development. The team should prioritise defining and stabilising the AnnualSummary domain model and the Supabase query contract early, ideally in a shared types package that dependent teams can code against using stubs. The offline cache dependency (summary-offline-cache) should be delivered in parallel to avoid a serial bottleneck. Testing must cover Supabase query correctness for boundary date ranges, transformation accuracy from raw rows to domain objects, cache read/write round-trip fidelity, and network-unavailable fallback behaviour.
RLS (Row Level Security) policies on the Supabase side must be validated to ensure mentors can only access their own activity records — a data privacy requirement with compliance implications.
The Annual Summary Repository implements the repository pattern over two data sources: Supabase (remote) and summary-offline-cache (local). The getActivitiesForPeriod method issues a Supabase query filtered by mentorId and a DateTime range, mapping each returned row to an Activity domain object; use generated Supabase types or a manual RowMapper to keep the transformation layer explicit and testable. getSummaryLastUpdated supports staleness checks in the BLoC and offline-cache layers. cacheSummary and getCachedSummary delegate directly to the summary-offline-cache interface — the repository does not own serialisation logic itself.
Implement a connectivity-aware strategy: attempt the remote fetch first, fall back to getCachedSummary on SocketException or timeout, and surface a clear domain-level error if both sources fail. Ensure DateTime handling uses UTC consistently to avoid timezone-related aggregation bugs across mentor locales. The interface is Future-based throughout, compatible with Dart's async/await model and testable via mockito or mocktail.
Responsibilities
- Query activity records for a mentor within a rolling date window
- Transform raw activity rows into AnnualSummary domain objects
- Write computed summaries to the local offline cache
- Return cached data when network is unavailable
Interfaces
getActivitiesForPeriod(mentorId: String, from: DateTime, to: DateTime): Future<List<Activity>>
getCachedSummary(mentorId: String, period: SummaryPeriod): Future<AnnualSummary?>
cacheSummary(mentorId: String, summary: AnnualSummary): Future<void>
clearCache(mentorId: String): Future<void>
getSummaryLastUpdated(mentorId: String): Future<DateTime?>
Relationships
Dependents (2)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component