Summary Generation Service
Component Detail
Description
Core backend service that orchestrates the production of periodic summaries. Triggered by the summary scheduler, it computes aggregated metrics per peer mentor and per coordinator team, writes results to the database, and enqueues push notifications.
summary-generation-service
Summaries
The Summary Generation Service is the analytical engine that transforms raw mentoring activity data into meaningful periodic performance reports for every mentor and coordinator team in the organisation. By automating this process — including year-over-year comparison and push notification delivery — the service eliminates manual reporting effort, ensures all users receive timely insights, and enables data-driven programme management at scale. The service enforces strict organisation-level data isolation, protecting participant privacy and regulatory compliance. Reliable, automated summaries drive engagement with the platform and provide leadership with the evidence base needed to demonstrate programme impact and secure continued investment.
Summary Generation Service is the highest-complexity backend component in this feature set, with dependencies on activity-aggregation-repository, summary-period-repository, and push-notification-dispatcher. It must be scheduled, triggered reliably, and complete within an acceptable time window for all organisations concurrently — making performance testing and load validation critical before release. Key delivery risks include data isolation bugs (cross-organisation leakage), incorrect period boundary calculations, and notification delivery failures. The component should be developed with full integration test coverage against realistic data volumes.
Plan for a dedicated QA cycle covering edge cases: no activity data, missing prior-period data, large organisations, and notification opt-out scenarios. Deployment requires coordination with the scheduler configuration.
SummaryGenerationService is a high-complexity backend service orchestrating the full periodic summary pipeline. Entry point is generateSummariesForPeriod(periodType, year, organisationId), which drives computeMentorSummary and computeTeamSummary using date ranges from the Period Calculator Service. Results are persisted via persistSummary(summary) and notifications enqueued via enqueuePushNotification(userId, summaryId) delegated to push-notification-dispatcher. All aggregation queries must be scoped by organisationId to enforce data isolation — this invariant must be validated at every data access layer call.
The compareWithPriorPeriod function should handle null gracefully when prior data is absent. Design for idempotency: re-running for the same period should upsert rather than duplicate. Integration with activity-aggregation-repository should use bulk-fetch patterns to avoid N+1 queries at scale.
Responsibilities
- Aggregate activity data for the current half-year or quarterly period
- Compute year-over-year comparison when prior-period data exists
- Persist generated summaries to the database
- Enqueue push notification jobs for affected users
- Enforce organisation-level data isolation throughout aggregation
Interfaces
generateSummariesForPeriod(periodType, year, organisationId)
computeMentorSummary(mentorId, dateRange)
computeTeamSummary(coordinatorId, dateRange)
compareWithPriorPeriod(current, priorRange)
persistSummary(summary)
enqueuePushNotification(userId, summaryId)
Relationships
Dependencies (3)
Components this component depends on
Dependents (2)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component