Background Jobs
PinTeach uses BullMQ + Redis for background job processing. All workers are initialized in apps/api/src/index.ts.
Workers
Section titled “Workers”| # | Worker | Schedule | Purpose |
|---|---|---|---|
| 1 | auto-complete | Per session | Complete sessions after end + grace period |
| 2 | calendar-sync | 5 min cron | Retry pending calendar sync records |
| 3 | drive-copy | On demand | Copy Drive files to student folders |
| 4 | drive-sync | 3 AM daily | Verify Drive file integrity |
| 5 | lifecycle-detection | 6 AM daily | Detect gaps, churn, streaks |
| 6 | content-analytics | Periodic | Aggregate content usage metrics |
| 7 | audit-cleanup | 1st of month, 2 AM | Clean old audit logs by retention tier |
| 8 | data-retention | Sunday 3 AM | GDPR data retention enforcement |
| 9 | waitlist-expiry | Hourly | Expire stale waitlist offers, cascade notifications |
| 10 | metric-alerts | Periodic | Monitor teacher KPI thresholds, generate alert notifications |
| 11 | scheduled-messages | Delayed jobs | Process scheduled contact reminders |
Worker Details
Section titled “Worker Details”Auto-Complete Worker
Section titled “Auto-Complete Worker”Scheduled per-session at endsAt + gracePeriodMinutes. Two modes:
- AUTO_COMPLETE: Session → completed, CreditLedger: CONSUME
- PENDING_REVIEW: Session → pending_review, notify teacher
Calendar Sync Worker
Section titled “Calendar Sync Worker”Every 5 minutes. Processes batch of 20 pending session_calendar_sync records. Skips if the google-calendar circuit breaker is open.
Drive Copy Worker
Section titled “Drive Copy Worker”On-demand (triggered when Drive resources are linked to sessions). Concurrency: 3. Protected by circuit breaker + rate limiter. Blocked jobs are re-queued with DelayedError.
Drive Sync Worker
Section titled “Drive Sync Worker”Daily at 3 AM. Verifies Drive file integrity by checking if files still exist. Marks trashed/deleted files in drive_file_copies.
Lifecycle Detection Worker
Section titled “Lifecycle Detection Worker”Daily at 6 AM. For all teachers, detects:
- Session gaps (no class in N days)
- Churn (no activity in N days)
- Expiring enrollments
- Session streaks (consistent weekly attendance)
Uses per-teacher retention_settings thresholds.
Content Analytics Worker
Section titled “Content Analytics Worker”Periodic aggregation of content usage metrics into content_analytics_cache. Powers the content insights dashboard.
Audit Cleanup Worker
Section titled “Audit Cleanup Worker”1st of each month at 2 AM. Batched deletes per retention tier:
- Financial: 7 years
- Student: 3 years
- General: 1 year
- Fallback: 6 months
Data Retention Worker
Section titled “Data Retention Worker”Sundays at 3 AM. Per-teacher GDPR enforcement:
- Auto-delete inactive students past threshold
- Clean old session content
- Clean old contact log entries
- Check overdue erasure requests
Waitlist Expiry Worker
Section titled “Waitlist Expiry Worker”Hourly. Expires notified waitlist entries past expiresAt (48h window). Auto-notifies the next person in line.
Metric Alerts Worker
Section titled “Metric Alerts Worker”Periodic metric alerts check. Monitors teacher KPI thresholds and generates notifications when metrics cross alert boundaries.
Scheduled Messages Worker
Section titled “Scheduled Messages Worker”Processes delayed BullMQ jobs for scheduled contact reminders. On fire: creates contact_log entry + teacher_notification. Teacher still manually contacts via WhatsApp/email. Recovers overdue pending messages on startup (re-enqueues with delay: 0).
Resilience
Section titled “Resilience”Workers use circuit breakers and rate limiters for external API calls:
- Circuit breaker: Redis-backed, shared across API + workers
- Rate limiter: Sliding-window, per-teacher + global levels
- Failed jobs: Re-queued with exponential backoff via BullMQ
Drive copy worker uses tryAcquire() — if rate limited, re-queues with DelayedError instead of waiting.