Schedule Module Overview

The Schedule module provides a narrow, internal scheduling facade for other NestJS modules. Callers inject IScheduleService to enqueue payloads for future delivery — either once at a specific UTC instant (scheduleAt) or on a repeating cron/interval pattern (scheduleRepeat). When a job fires, the module emits an in-process schedule.arrived event that registered @OnEvent listeners consume. The module handles retry, cancellation, rescheduling, and boot-time reconciliation transparently.

Designed for: task reminders, AI agent scheduled triggers, time-boxed notification workflows, and any domain that needs deferred in-process work without owning a queue.

Does NOT provide: HTTP controllers, cross-process workers, per-user quotas, authentication/authorization checks, DLQ queues, or RRULE recurrence.

Architecture

This module follows a Hexagonal / Clean Architecture layout:

• Domain: ScheduledJob entity, value objects (ScheduleTopicVo, ScheduleTimezoneVo, …), IScheduleService interface, IScheduleArrivedEvent contract.
• Application: ScheduleServiceImpl delegates to six use-cases. ScheduleReconcilerService heals Redis on boot.
• Infrastructure: BullMqScheduleQueueAdapter (timing + retry), ScheduledJobRepositoryImpl (Postgres source of truth), EventEmitterSchedulePublisherAdapter (@nestjs/event-emitter delivery), ScheduleMetricsAdapter (OTel metrics).
• Presentation: none in v1.

Sub-Domains

• Domain
• Features
• Job Scheduling
• Retry and Failure
• Observability
• Runbooks