Scheduler Module Specification

1. Purpose & Overview

scheduler

2. Responsibilities

• Execute periodic task

  scheduler_heartbeat

  and

  cleanup_stale_jobs

  .
• Manage bulk broadcast batch execution via

  process_scheduler_job

  .
• Enforce 50 msgs/sec rate limits per tenant.

3. Directory Structure

services/api/scheduler/
├── admin.py
├── apps.py
├── services/
│   ├── async_whatsapp.py
│   └── rate_limiter.py
├── tasks.py
└── tests/

4. Models & Database Schemas

• Integrates with

  django_celery_beat.models.PeriodicTask

  and

  campaigns.Campaign

  .

5. Services & Business Logic

• TokenBucketRateLimiter

  : Redis-backed token bucket rate limiter.

• AsyncWhatsAppClient

  : Async HTTP client for Meta Graph API calls.

6. Serializers & Data Transfer Objects

• Task payload tuples containing recipient phone numbers, template IDs, and parameter bindings.

7. Views & API Endpoints

• None (Scheduler is an internal task execution engine).

8. Permissions & Role Rules

• System-level access (runs via Celery daemon).

9. Signals & Event Listeners

• Listens for campaign

  SCHEDULED

  transitions to enqueue jobs.

10. Background Tasks & Celery Jobs

• scheduler.tasks.scheduler_heartbeat

  : Beat task running every minute.

• scheduler.tasks.process_scheduler_job

  : Worker task processing batch dispatches.

11. Data Flow & External Dependencies

• Uses Redis for task queuing and token bucket state; sends requests to Meta Cloud API (

  v22.0

  ).

12. Business Rules & Validations

• Jobs that fail due to temporary network issues are retried according to

  SCHEDULER_RETRY_DELAYS = [60, 300, 900]

  .

13. Sequence Diagram (Mermaid)

14. Known Limitations & Technical Debt

• Single worker concurrency can bottleneck if Redis network latency increases.

15. Future Improvements

• Dynamic rate-limit adjustment based on Meta Quality Rating feedback.