Summary Period Repository
Component Detail
Description
Manages CRUD operations for generated periodic summary records in the database. Provides queries to fetch the latest summary for a user and period type, preventing duplicate generation runs.
summary-period-repository
Summaries
The Summary Period Repository is the record-keeping backbone of the periodic reporting system, ensuring that every generated summary is persisted reliably and that the organisation always has an accurate, up-to-date audit trail of mentor performance data. By preventing duplicate summary generation, it protects the integrity of reports presented to leadership and funding bodies, avoiding the confusion and trust erosion that comes from contradictory data. The delivery-tracking capability — marking summaries as sent after push notification dispatch — provides operational visibility into programme communications, supporting accountability and governance requirements that institutional clients increasingly demand as part of enterprise procurement criteria.
The Summary Period Repository is a low-complexity CRUD data component with a clearly bounded scope, making it a good candidate for early delivery to unblock the summary generation service and scheduler. Key delivery considerations include ensuring the uniqueness constraint on (userId, periodType, year, quarter) is enforced at the database level to complement the application-level duplicate check. The `markAsDelivered` interface introduces a two-phase lifecycle for summary records (generated → delivered) that must be reflected in database migrations and tested end-to-end with the push notification pipeline. Organisation-scoped `getAll` queries must be validated for access control.
Overall risk is low, with the main concern being migration safety in production environments with existing data.
The Summary Period Repository provides five interfaces over the `periodic_summaries` database table: `save`, `findByUserAndPeriod`, `findTeamSummary`, `markAsDelivered`, and `getAll`. The `findByUserAndPeriod` and `findTeamSummary` methods act as idempotency guards — callers should invoke these before calling `save` to prevent duplicate records. A unique constraint on `(user_id, period_type, year, quarter)` should be enforced at the DB schema level as a safety net. `markAsDelivered` should perform an atomic update setting a `delivered_at` timestamp rather than a boolean to preserve auditability.
`getAll` accepts `organisationId` and should be protected by RLS to prevent cross-tenant access. The periodic-summary data model drives the record shape; ensure the TypeScript interface is shared with the summary generation service to maintain type safety.
Responsibilities
- Persist newly generated periodic summary records
- Retrieve current-period summary for a given user and period type
- Detect whether a summary has already been generated for a period
- Mark summaries as delivered after push notification is sent
Interfaces
save(summary)
findByUserAndPeriod(userId, periodType, year, quarter)
findTeamSummary(coordinatorId, periodType, year, quarter)
markAsDelivered(summaryId)
getAll(organisationId, periodType, year)
Relationships
Related Data Entities (1)
Data entities managed by this component