Campaigns Module Specification

1. Purpose & Overview

campaigns

2. Responsibilities

• Maintain

  Campaign

  and

  CampaignRecipient

  models.
• Track campaign states (

  DRAFT

  ,

  SCHEDULED

  ,

  RUNNING

  ,

  PAUSED

  ,

  COMPLETED

  ,

  FAILED

  ).
• Interface with the

  scheduler

  module for executing mass broadcast dispatches.

3. Directory Structure

services/api/campaigns/
├── admin.py
├── apps.py
├── migrations/
├── models.py
├── serializers.py
└── views.py

4. Models & Database Schemas

class CampaignStatus(models.TextChoices):
    DRAFT = 'DRAFT', 'Draft'
    SCHEDULED = 'SCHEDULED', 'Scheduled'
    RUNNING = 'RUNNING', 'Running'
    PAUSED = 'PAUSED', 'Paused'
    COMPLETED = 'COMPLETED', 'Completed'
    FAILED = 'FAILED', 'Failed'

class Campaign(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    tenant = models.ForeignKey('tenants.Tenant', on_delete=models.CASCADE)
    name = models.CharField(max_length=255)
    status = models.CharField(max_length=20, choices=CampaignStatus.choices, default=CampaignStatus.DRAFT)
    template = models.ForeignKey('templates.Template', on_delete=models.PROTECT)
    scheduled_at = models.DateTimeField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

5. Services & Business Logic

• Campaign.start_broadcast()

  : Transition state to

  RUNNING

  and trigger background worker dispatch.

• Campaign.calculate_analytics()

  : Computes total sent, delivered, read, and failed counts.

6. Serializers & Data Transfer Objects

• CampaignSerializer

  : Validates template selection and execution parameters.

• CampaignDetailSerializer

  : Includes analytics metrics and recipient breakdown.

7. Views & API Endpoints

• GET /api/campaigns/

  : List campaigns for active tenant.

• POST /api/campaigns/

  : Create new broadcast campaign.

• GET /api/campaigns/{id}/

  : Retrieve campaign analytics.

8. Permissions & Role Rules

• TENANT_ADMIN

  &

  TENANT_USER

  : Can create and view campaigns within their active tenant.

9. Signals & Event Listeners

• post_save

  : Notifies operators upon campaign completion or failure.

10. Background Tasks & Celery Jobs

• Tasks dispatched to

  scheduler.tasks.process_scheduler_job

  .

11. Data Flow & External Dependencies

• Interfaces with

  templates

  module for HSM template validation and

  scheduler

  module for Celery execution.

12. Business Rules & Validations

• Campaigns cannot be executed without a Meta-approved HSM message template.
• Scheduled time

  scheduled_at

  must be in the future.

13. Sequence Diagram (Mermaid)

14. Known Limitations & Technical Debt

• Recipient lists are stored as relational foreign keys (can incur database I/O overhead for campaigns exceeding 100,000 recipients).

15. Future Improvements

• Implement chunked recipient storage using Redis Bitmaps or Parquet files for ultra-large broadcasts (> 1 million recipients).