04 — Information Architecture (Scheduler Module)
- 1. Backend IA — module composition
- 2. Job taxonomy
- 3. Console IA — Scheduled Jobs (superadmin,
(proposed)) - 4. Relationship to other modules
- 5. Navigation & routing
Backend: the module's runtime structure (queues ⇄ triggers). Console: the operator-facing IA of the Scheduled Jobs admin area —
(proposed)unless an endpoint is cited. The console is a platform-level (superadmin) surface, sibling of Security/API Keys in the admin settings cluster.
1. Backend IA — module composition
SchedulerModule (scheduler.module.ts:12-23)
├── SchedulerController GET/POST/DELETE /scheduler (scheduler.controller.ts:19-46)
├── SchedulerService onModuleInit → registerDefaults (scheduler.service.ts:43-45)
│ ├── 10 repeatable jobs ──► 10 queues (scheduler.service.ts:48-119)
│ └── listJobs / createJob / removeJob (scheduler.service.ts:152-226)
├── Jobs (providers, scheduler.module.ts:15-22)
│ ├── OverdueScanJob → queue.add('check-overdue') (overdue-scan.job.ts:12-19)
│ ├── DailyDigestJob → queue.add('send-daily-digest') (daily-digest.job.ts:12-25)
│ ├── FeeReminderJob → InvoiceRepository scan + per-invoice enqueue (fee-reminder.job.ts:16-47)
│ └── AttendanceReportJob → queue.add('generate-attendance-report') (attendance-report.job.ts:13-28)
└── CreateScheduleDto cron + queue whitelist (dto/create-schedule.dto.ts:18-41)
Queue registry: 15 queues + DLQ registered in BullMqModule
(bullmq.module.ts:28-45); names in queue.constants.ts:1-17; event-driven
routes in event-queue-map.ts:6-43 (scheduler triggers bypass the map and
enqueue directly by queue.add).
2. Job taxonomy
| Kind | Example | Source |
|---|---|---|
| Default repeatable (10) | overdue-scan, daily-digest, dashboard-rebuild, biometric-sync, audit-flush, retention-archive, fee-reminder, attendance-report-daily, admission-reminder-scan, admission-expiry-scan | scheduler.service.ts:48-119 |
| Custom repeatable (operator) | any 5-field cron on 11 whitelisted queues | create-schedule.dto.ts:4-16 |
| Fan-out child jobs | check-overdue, send-daily-digest, send-payment-reminder, generate-attendance-report | jobs/*.job.ts |
| Event-driven jobs | send-welcome-email, log-login, … | event-queue-map.ts:6-43 |
3. Console IA — Scheduled Jobs (superadmin, (proposed))
Admin Settings
└── Scheduled Jobs (/admin/scheduler)
├── Jobs List (S1) → GET /scheduler ✓ today
│ ├── Job Detail (S2) run history + next run (proposed)
│ │ └── Job Logs (S4) per-run log stream (proposed)
│ └── Create Schedule (S3) POST /scheduler ✓ today
└── Dead Letter Queue (S6) failed-after-retry rows (proposed)
└── DLQ Record detail: originalQueue/jobId, failedReason, attemptsMade (dlq.setup.ts:12-21)
Content model of a job row (from scheduler.service.ts:152-186):
queue • name • pattern • tz
+ (proposed) lastRunAt • lastStatus • nextRunAt • runs24h • avgDurationMs
Content model of a DLQ row (from dlq.setup.ts:12-21):
originalQueue • originalJobId • originalJobName • data
failedReason • attemptsMade • failedAt
4. Relationship to other modules
| Module | Through | Direction |
|---|---|---|
| Fees | invoice-generate, payment-reminder queues; FeesModule import (scheduler.module.ts:13) | scheduler triggers, fees processes |
| Attendance / Reports | attendance-process, report-generate | scheduler triggers, workers process |
| Notifications | emails, in-app, push | scheduler triggers digests/reminders |
| CRM | admission-reminder, admission-expiry | scheduler scans lifecycle |
| Audit | audit-write | audit-flush cadence |
| Infra | Redis (BullMQ), DLQ (dlq.setup.ts), IdempotencyService (bullmq.module.ts:76) | delivery guarantees |
5. Navigation & routing
- Console root:
/admin/scheduler(nested under admin settings). - Job detail:
/admin/scheduler/jobs/:queue/:name(queue+name disambiguate —fee-reminder≠attendance-report-daily, both daily patternsscheduler.service.ts:92-104). - DLQ:
/admin/scheduler/dlq+/admin/scheduler/dlq/:jobId. - Existing endpoints stay under
/api/v1/scheduler(scheduler.controller.ts:19— URI versioning frommain.ts).