Bufdir Activity Query Service
Component Detail
Description
Queries and filters activity records from the database scoped to a specific organisation, date range, and optionally activity type. Returns a structured dataset ready for Bufdir column mapping. Handles multi-chapter membership de-duplication to prevent double-counting.
bufdir-activity-query-service
Summaries
The Bufdir Activity Query Service is the data foundation of the entire Bufdir reporting process and a critical financial risk management component. It ensures that activity records submitted to Bufdir are accurate, correctly scoped to each organisation's reporting period, and free of duplicate counts — directly protecting the organisation's compliance standing and the integrity of the funding data it reports. A particularly high-value function is preventing double-counting of participants who belong to multiple chapters: without this safeguard, inflated participation figures could create regulatory exposure and affect government funding allocations. Correct activity counts have direct financial consequences for all partner organisations, making the accuracy of this component a board-level risk concern.
The Bufdir Activity Query Service is a high-complexity backend component with no external service dependencies, making it a strong candidate for early parallel development alongside other export sub-services. However, its internal complexity is substantial: the multi-chapter de-duplication logic requires deep understanding of the contact and membership data model, and correctness is critical — bugs produce incorrect Bufdir submissions with potential regulatory consequences.
Allocate dedicated QA cycles for de-duplication edge cases (contacts with three or more chapter memberships, overlapping reporting periods), large dataset performance testing, and data completeness validation scenarios. This component should reach unit test coverage targets first, as the orchestrator and column mapper both depend on the stability of its `ActivityRow` output schema. Document that schema as a formal interface contract before downstream teams begin integration.
The Bufdir Activity Query Service is a high-complexity backend service querying the `activity`, `peer_mentor`, and `contact` data models. It exposes four interfaces: `queryActivities(orgId, period, activityTypes?)` returning structured `ActivityRow` records, `countActivities(orgId, period)` for pre-export row estimation surfaced in the confirmation dialog, `getUniqueParticipants(orgId, period)` for participant-level analytics, and `validateDataCompleteness(rows)` to surface missing required fields before export begins. The de-duplication algorithm for multi-chapter contacts is the highest-risk implementation area — define a canonical strategy (e.g., unique by contactId + activityDate + activityType within the period) and cover it exhaustively with unit tests before integration. Queries must be paginated or streamed for large datasets to avoid memory pressure.
Index the activity table on (orgId, activityDate, activityType) for query performance. The `ActivityRow` type is a shared interface contract; version it explicitly if the schema evolves.
Responsibilities
- Query activity records filtered by org, date range, and activity type
- De-duplicate activities for contacts with multi-chapter memberships
- Return structured rows with all fields required by Bufdir's column schema
Interfaces
queryActivities(String orgId, DateRange period, List<String>? activityTypes)
countActivities(String orgId, DateRange period)
getUniqueParticipants(String orgId, DateRange period)
validateDataCompleteness(List<ActivityRow> rows)
Relationships
Related Data Entities (4)
Data entities managed by this component