Period Record Count Service
Component Detail
Description
Queries the aggregated activity data to return the number of records that fall within a given date range. Delegates to the Bufdir data aggregation layer and exposes a lightweight count endpoint consumed by the UI banner.
period-record-count-service
Summaries
The Period Record Count Service provides the real-time data assurance layer that tells report authors exactly how many activity records exist for a chosen reporting window before they submit. This is a direct risk-reduction mechanism: without it, staff could submit reports covering periods with missing or incomplete data without any warning, leading to under-reporting of activities and potential funding implications. By surfacing record counts and flagging future end dates or incomplete periods, the service gives organizations the information needed to submit with confidence. The downstream effect is fewer rejected or queried reports from Bufdir and stronger trust in the organization's data governance.
Period Record Count Service is a low-complexity backend service but sits on the critical path for the report submission confirmation flow, which means it must be ready before the Record Count Confirmation Banner UI can be end-to-end tested. Its dependency on bufdir-aggregation-repository means scheduling must account for that layer being available and returning stable test data. Development is two to three days including unit and integration tests. A key risk is performance: count queries over large activity datasets can be slow, so the service should be tested with realistic data volumes early.
The async stream interface (getCountStream) adds implementation complexity that should be scoped and estimated separately from the simpler synchronous count endpoint.
Period Record Count Service is a backend service that queries activity data to return record counts within a given DateTimeRange for a specific organization. It depends on bufdir-aggregation-repository for data access. Three methods are exposed: countRecordsInRange(String orgId, DateTimeRange range) returns a Future
The service delegates all data access to bufdir-aggregation-repository and must not contain raw query logic. Data models used are activity and report-period. Ensure the isPeriodComplete logic uses a server-side clock, not a client-supplied timestamp, to prevent spoofing. Cache invalidation should be considered if the same range is queried repeatedly within a session.
Responsibilities
- Count activity records within a DateTimeRange
- Determine whether the period end date is in the future
- Return count asynchronously to avoid blocking the UI
Interfaces
countRecordsInRange(String orgId, DateTimeRange range)
isPeriodComplete(DateTimeRange range)
getCountStream(String orgId, DateTimeRange range)
Relationships
Dependents (2)
Components that depend on this component
Related Data Entities (1)
Data entities managed by this component