Summary Generation Scheduler
Component Detail
Description
Supabase scheduled Edge Function that triggers the summary generation service at the start of each half-year and quarterly period boundary. Manages idempotent execution to prevent duplicate summaries if the function is retried.
summary-scheduler
Summaries
The Summary Generation Scheduler is the automated engine that ensures every mentor and coordinator receives their performance report at the right moment — at the start of each half-year and quarterly period — without requiring any manual intervention from programme administrators. This automation eliminates the operational overhead of running reports by hand, reduces the risk of missed or delayed communications, and ensures consistent delivery across all organisations on the platform simultaneously. Reliable, timely reporting strengthens user trust in the programme, increases engagement with feedback, and demonstrates to institutional clients that the platform operates with the operational discipline expected of enterprise software.
The Summary Generation Scheduler is a medium-complexity backend infrastructure component delivered as a Supabase Edge Function with a cron trigger. Key delivery dependencies include the summary generation service being fully tested and the run-lock mechanism being validated for idempotency before the scheduler is activated in production. The cron expressions for half-year (January, July) and quarterly boundaries must be configured in the correct timezone relative to the organisation's locale — this is a common source of off-by-one period errors and requires explicit QA. The run-lock (`acquireRunLock` / `releaseRunLock`) must be tested under retry conditions to confirm it prevents duplicate generation when Supabase retries a failed invocation.
Deployment requires Supabase project-level cron configuration and should be gated behind a feature flag for initial rollout.
The Summary Generation Scheduler is implemented as a Supabase scheduled Edge Function exposing five interfaces: `scheduleHalfYearRun`, `scheduleQuarterlyRun`, `executeSummaryJob`, `acquireRunLock`, and `releaseRunLock`. Scheduling uses Supabase's pg_cron or Edge Function schedule syntax; cron expressions should be stored as configuration constants, not hardcoded. `executeSummaryJob` accepts `periodType` and `organisationIds`, delegating to the Summary Generation Service — it must not inline generation logic. The run-lock pattern should use a dedicated `scheduler_locks` table with a unique constraint on `job_id`, inserting on acquire and deleting on release within a transaction; a TTL or `pg_try_advisory_lock` can serve as a fallback to prevent orphaned locks if the function crashes mid-execution.
All execution outcomes (success, lock contention, error) must be logged with structured metadata for observability. Depends exclusively on the summary-generation-service contract being stable.
Responsibilities
- Trigger summary generation at half-year period boundaries (January, July)
- Trigger summary generation at quarterly period boundaries
- Pass the resolved period type and organisation scope to the generation service
- Ensure idempotent execution using a run-lock mechanism
Interfaces
scheduleHalfYearRun(cronExpression)
scheduleQuarterlyRun(cronExpression)
executeSummaryJob(periodType, organisationIds)
acquireRunLock(jobId)
releaseRunLock(jobId)
Relationships
Related Data Entities (2)
Data entities managed by this component