Bufdir Metrics Repository
Component Detail
Description
Data access layer for reading raw activity/event/contact data and persisting computed Bufdir metric snapshots. Wraps Supabase table queries and RPC function calls, providing a typed interface consumed by the aggregation service.
bufdir-metrics-repository
Summaries
The Bufdir Metrics Repository is the data access foundation that makes reliable, auditable reporting possible. It provides a governed interface between the reporting system and the underlying Supabase database, ensuring that all raw activity and participant data is read consistently and that computed reporting snapshots are persisted for audit and caching purposes. From a business perspective, the snapshot persistence capability is particularly valuable: it means that once a reporting period is aggregated and submitted, the exact metrics payload is preserved and can be retrieved for future reference, audit responses, or dispute resolution — protecting the organization if questions arise about a historical submission months or years later.
This is a medium-complexity data-layer component that underpins the entire aggregation pipeline — every other service in the Bufdir reporting feature ultimately reads through this repository. Its early delivery is essential since it cannot be integration-tested in isolation; the aggregation service needs it functional to validate end-to-end flows. The getRawAggregationFromRpc() interface wraps Supabase stored procedures, which means any changes to Supabase RPC function signatures require coordinated updates here — establish a contract between the database team and this component's owner. The saveMetricsSnapshot() and deleteMetricsSnapshot() interfaces imply a snapshots table that needs schema definition and migration scripting.
Ensure this is included in the database migration plan early to avoid blocking the aggregation service integration.
The repository wraps Supabase's Dart client and maps raw query results to typed domain models consumed by the aggregation service. The getRawAggregationFromRpc() method is a thin wrapper over Supabase's rpc() call — ensure the RPC function name and parameter schema are version-controlled alongside this component. The saveMetricsSnapshot() method should use an upsert pattern (insert or replace by orgId + periodId) to support re-aggregation without orphaned snapshot records. For getActivitiesForPeriod(), getEventsForPeriod(), and getContactInteractionsForPeriod(), implement cursor-based pagination or streaming reads to support large datasets — NHF's scale means naive SELECT * queries will hit Supabase's response size limits.
All reads must pass orgId through every query to enforce row-level security at the database layer, never relying solely on the MultiOrgDataIsolator caller. Cache the getMetricsSnapshot() result in memory within a single aggregation run to avoid redundant reads.
Responsibilities
- Read activity, event, and contact records for a given org and period
- Persist aggregated metric snapshots for caching and audit
- Expose Supabase RPC function results as typed Dart models
- Support incremental reads for large datasets
Interfaces
getActivitiesForPeriod(orgId, periodId)
getEventsForPeriod(orgId, periodId)
getContactInteractionsForPeriod(orgId, periodId)
saveMetricsSnapshot(orgId, periodId, metrics)
getMetricsSnapshot(orgId, periodId)
deleteMetricsSnapshot(orgId, periodId)
getRawAggregationFromRpc(orgId, periodId)
Relationships
Dependents (2)
Components that depend on this component