┌─────────────────┐      ┌──────────────────────┐      ┌─────────────────┐
│  Vite Frontend  │──────│   Express API        │──────│  PostgreSQL DB  │
│ (React/Vue UI)  │ HTTP │   (Campaign Mgmt)    │      │  (Contacts,     │
│                 │      │                      │      │   Campaigns)    │
└─────────────────┘      └──────────────────────┘      └─────────────────┘
        │                         │
        │                         │
        │                 ┌───────▼──────────┐      ┌─────────────────┐
        │                 │   BullMQ Queue   │──────│   Redis Store   │
        │                 │ (Bulk Processor) │      │                 │
        │                 └───────┬──────────┘      └─────────────────┘
        │                         │
        │                         │ Rate-limited sends
        │                         │
        │                 ┌───────▼──────────┐      ┌─────────────────┐
        └─────────────────│  Plivo SMS API   │──────│  User's Phone   │
                          │  (Delivery)      │      │                 │
                          └──────────────────┘      └─────────────────┘

Flow:
1. User creates campaign in frontend UI
2. Frontend sends campaign config to Express API
3. API stores campaign in PostgreSQL
4. Campaign scheduled → jobs queued in BullMQ
5. Queue workers process messages with rate limiting
6. Plivo API delivers SMS to recipients
7. Delivery reports collected and stored
8. Analytics displayed in frontend dashboard

import * as plivo from 'plivo';

export class PlivoService {
  private client: plivo.Client;
  private sourceNumber: string;

  constructor() {
    const authId = process.env.PLIVO_AUTH_ID;
    const authToken = process.env.PLIVO_AUTH_TOKEN;
    this.sourceNumber = process.env.PLIVO_PHONE_NUMBER!;

    if (!authId || !authToken) {
      throw new Error('Plivo credentials not configured');
    }

    this.client = new plivo.Client(authId, authToken);
  }

  /**
   * Send a single SMS message
   * @param to - Recipient phone number in E.164 format
   * @param text - Message content (max 160 characters for single SMS)
   * @returns Plivo message response with message UUID
   */
  async sendSingleMessage(to: string, text: string): Promise<any> {
    try {
      const response = await this.client.messages.create({
        src: this.sourceNumber,
        dst: to,
        text: text,
        url: `${process.env.BASE_URL}/webhooks/plivo/status`, // Delivery callback
      });

      return response;
    } catch (error: any) {
      console.error('Plivo send error:', error);
      throw new Error(`Failed to send SMS: ${error.message}`);
    }
  }

  /**
   * Send bulk messages using Plivo's bulk messaging API
   * Supports up to 1,000 recipients per request
   * Reference: https://www.plivo.com/docs/messaging/api/message/bulk-messaging
   * @param recipients - Array of phone numbers (E.164 format)
   * @param text - Message content
   * @returns Array of message UUIDs
   */
  async sendBulkMessage(recipients: string[], text: string): Promise<string[]> {
    if (recipients.length === 0) {
      throw new Error('No recipients provided');
    }

    if (recipients.length > 1000) {
      throw new Error('Bulk messaging limited to 1,000 recipients per request');
    }

    try {
      // Join recipients with < delimiter as required by Plivo
      const dstString = recipients.join('<');

      const response = await this.client.messages.create({
        src: this.sourceNumber,
        dst: dstString,
        text: text,
        url: `${process.env.BASE_URL}/webhooks/plivo/status`,
      });

      return response.message_uuid || [];
    } catch (error: any) {
      console.error('Plivo bulk send error:', error);
      throw new Error(`Failed to send bulk SMS: ${error.message}`);
    }
  }

  /**
   * Retrieve message details and delivery status
   * @param messageUuid - Plivo message UUID
   */
  async getMessageStatus(messageUuid: string): Promise<any> {
    try {
      const response = await this.client.messages.get(messageUuid);
      return response;
    } catch (error: any) {
      console.error('Error retrieving message status:', error);
      throw error;
    }
  }
}

import { AppDataSource } from '../config/database';
import { Campaign, CampaignStatus } from '../entities/Campaign';
import { Contact } from '../entities/Contact';
import { Message, MessageStatus } from '../entities/Message';
import { OptOut } from '../entities/OptOut';
import { SmsQueue } from '../queues/SmsQueue';

export class CampaignService {
  private campaignRepo = AppDataSource.getRepository(Campaign);
  private contactRepo = AppDataSource.getRepository(Contact);
  private messageRepo = AppDataSource.getRepository(Message);
  private optOutRepo = AppDataSource.getRepository(OptOut);
  private smsQueue = new SmsQueue();

  /**
   * Create a new campaign
   */
  async createCampaign(data: {
    name: string;
    messageTemplate: string;
    scheduledAt?: Date;
    segmentCriteria?: Record<string, any>;
  }): Promise<Campaign> {
    const campaign = this.campaignRepo.create({
      ...data,
      status: CampaignStatus.DRAFT,
    });

    return await this.campaignRepo.save(campaign);
  }

  /**
   * Get campaign recipients based on segment criteria
   * Filters out opted-out contacts
   */
  async getCampaignRecipients(campaignId: string): Promise<Contact[]> {
    const campaign = await this.campaignRepo.findOneBy({ id: campaignId });
    if (!campaign) {
      throw new Error('Campaign not found');
    }

    // Get all opted-out phone numbers
    const optOuts = await this.optOutRepo.find();
    const optedOutNumbers = optOuts.map(o => o.phoneNumber);

    // Build query based on segment criteria
    let query = this.contactRepo.createQueryBuilder('contact')
      .where('contact.isActive = :isActive', { isActive: true })
      .andWhere('contact.phoneNumber NOT IN (:...optedOut)', {
        optedOut: optedOutNumbers.length > 0 ? optedOutNumbers : ['']
      });

    // Apply segment filters
    if (campaign.segmentCriteria) {
      const { tags } = campaign.segmentCriteria;
      if (tags && tags.length > 0) {
        query = query.andWhere('contact.tags && ARRAY[:...tags]', { tags });
      }
    }

    return await query.getMany();
  }

  /**
   * Personalize message template with contact data
   */
  personalizeMessage(template: string, contact: Contact): string {
    let message = template;
    message = message.replace(/\{\{firstName\}\}/g, contact.firstName || '');
    message = message.replace(/\{\{lastName\}\}/g, contact.lastName || '');
    message = message.replace(/\{\{email\}\}/g, contact.email || '');

    // Replace custom fields
    if (contact.customFields) {
      Object.entries(contact.customFields).forEach(([key, value]) => {
        message = message.replace(
          new RegExp(`\\{\\{${key}\\}\\}`, 'g'),
          String(value)
        );
      });
    }

    return message.trim();
  }

  /**
   * Schedule campaign for sending
   * Creates message records and queues them in BullMQ
   */
  async scheduleCampaign(campaignId: string): Promise<void> {
    const campaign = await this.campaignRepo.findOneBy({ id: campaignId });
    if (!campaign) {
      throw new Error('Campaign not found');
    }

    // Get recipients
    const recipients = await this.getCampaignRecipients(campaignId);

    if (recipients.length === 0) {
      throw new Error('No eligible recipients found for campaign');
    }

    // Create message records
    const messages = recipients.map(contact => {
      const messageBody = this.personalizeMessage(campaign.messageTemplate, contact);

      return this.messageRepo.create({
        campaignId: campaign.id,
        contactId: contact.id,
        messageBody,
        status: MessageStatus.QUEUED,
      });
    });

    await this.messageRepo.save(messages);

    // Update campaign
    campaign.status = CampaignStatus.SCHEDULED;
    campaign.totalRecipients = recipients.length;
    await this.campaignRepo.save(campaign);

    // Queue messages in BullMQ
    for (const message of messages) {
      const contact = recipients.find(c => c.id === message.contactId);
      if (contact) {
        await this.smsQueue.addMessage({
          messageId: message.id,
          campaignId: campaign.id,
          to: contact.phoneNumber,
          text: message.messageBody,
        }, {
          delay: campaign.scheduledAt
            ? campaign.scheduledAt.getTime() - Date.now()
            : 0,
        });
      }
    }
  }

  /**
   * Get campaign analytics
   */
  async getCampaignAnalytics(campaignId: string) {
    const campaign = await this.campaignRepo.findOneBy({ id: campaignId });
    if (!campaign) {
      throw new Error('Campaign not found');
    }

    const messages = await this.messageRepo.findBy({ campaignId });

    const analytics = {
      totalRecipients: campaign.totalRecipients,
      queued: messages.filter(m => m.status === MessageStatus.QUEUED).length,
      sent: messages.filter(m => m.status === MessageStatus.SENT).length,
      delivered: messages.filter(m => m.status === MessageStatus.DELIVERED).length,
      failed: messages.filter(m => m.status === MessageStatus.FAILED).length,
      deliveryRate: campaign.totalRecipients > 0
        ? (campaign.deliveredCount / campaign.totalRecipients * 100).toFixed(2)
        : 0,
    };

    return analytics;
  }
}

import { Queue, Worker, Job } from 'bullmq';
import IORedis from 'ioredis';
import { PlivoService } from '../services/PlivoService';
import { AppDataSource } from '../config/database';
import { Message, MessageStatus } from '../entities/Message';
import { Campaign } from '../entities/Campaign';

interface SmsJobData {
  messageId: string;
  campaignId: string;
  to: string;
  text: string;
}

export class SmsQueue {
  private queue: Queue;
  private worker: Worker;
  private plivoService: PlivoService;
  private connection: IORedis;

  constructor() {
    this.connection = new IORedis({
      host: process.env.REDIS_HOST || 'localhost',
      port: parseInt(process.env.REDIS_PORT || '6379'),
      password: process.env.REDIS_PASSWORD || undefined,
      maxRetriesPerRequest: null,
    });

    this.queue = new Queue('sms-queue', { connection: this.connection });
    this.plivoService = new PlivoService();

    this.initWorker();
  }

  private initWorker() {
    const maxMessagesPerSecond = parseInt(process.env.MAX_MESSAGES_PER_SECOND || '10');

    this.worker = new Worker('sms-queue', async (job: Job<SmsJobData>) => {
      return await this.processMessage(job.data);
    }, {
      connection: this.connection,
      limiter: {
        max: maxMessagesPerSecond,
        duration: 1000, // Per second
      },
      concurrency: 5,
    });

    this.worker.on('completed', (job) => {
      console.log(`Job ${job.id} completed successfully`);
    });

    this.worker.on('failed', (job, err) => {
      console.error(`Job ${job?.id} failed:`, err);
    });
  }

  /**
   * Add message to queue
   */
  async addMessage(data: SmsJobData, options?: { delay?: number }) {
    return await this.queue.add('send-sms', data, {
      delay: options?.delay || 0,
      attempts: 3,
      backoff: {
        type: 'exponential',
        delay: 5000,
      },
      removeOnComplete: {
        count: 1000,
      },
      removeOnFail: {
        count: 5000,
      },
    });
  }

  /**
   * Process individual message
   * Respects quiet hours (8 AM - 9 PM local time per TCPA)
   */
  private async processMessage(data: SmsJobData): Promise<void> {
    const messageRepo = AppDataSource.getRepository(Message);
    const campaignRepo = AppDataSource.getRepository(Campaign);

    const message = await messageRepo.findOneBy({ id: data.messageId });
    if (!message) {
      throw new Error(`Message ${data.messageId} not found`);
    }

    // Check quiet hours (TCPA compliance)
    const currentHour = new Date().getHours();
    const quietStart = parseInt(process.env.QUIET_HOURS_START || '21');
    const quietEnd = parseInt(process.env.QUIET_HOURS_END || '8');

    if (currentHour >= quietStart || currentHour < quietEnd) {
      // Reschedule for next morning at 9 AM
      const tomorrow = new Date();
      tomorrow.setDate(tomorrow.getDate() + 1);
      tomorrow.setHours(9, 0, 0, 0);

      throw new Error('Quiet hours - rescheduling'); // Will trigger retry
    }

    try {
      // Send via Plivo
      const response = await this.plivoService.sendSingleMessage(data.to, data.text);

      // Update message record
      message.status = MessageStatus.SENT;
      message.plivoMessageUuid = response.message_uuid?.[0];
      message.sentAt = new Date();
      await messageRepo.save(message);

      // Update campaign counters
      const campaign = await campaignRepo.findOneBy({ id: data.campaignId });
      if (campaign) {
        campaign.sentCount += 1;
        await campaignRepo.save(campaign);
      }

    } catch (error: any) {
      message.status = MessageStatus.FAILED;
      message.errorMessage = error.message;
      await messageRepo.save(message);

      // Update campaign
      const campaign = await campaignRepo.findOneBy({ id: data.campaignId });
      if (campaign) {
        campaign.failedCount += 1;
        await campaignRepo.save(campaign);
      }

      throw error;
    }
  }

  /**
   * Close connections
   */
  async close() {
    await this.queue.close();
    await this.worker.close();
    this.connection.disconnect();
  }
}

import { Request, Response } from 'express';
import { CampaignService } from '../services/CampaignService';

export class CampaignController {
  private campaignService = new CampaignService();

  createCampaign = async (req: Request, res: Response) => {
    try {
      const { name, messageTemplate, scheduledAt, segmentCriteria } = req.body;

      // Validation
      if (!name || !messageTemplate) {
        return res.status(400).json({
          error: 'Name and message template are required'
        });
      }

      // Validate message includes opt-out instruction (TCPA requirement)
      const hasOptOut = messageTemplate.toLowerCase().includes('stop') ||
                        messageTemplate.toLowerCase().includes('opt-out');

      if (!hasOptOut) {
        return res.status(400).json({
          error: 'Message must include opt-out instructions (e.g., "Reply STOP to opt-out")'
        });
      }

      const campaign = await this.campaignService.createCampaign({
        name,
        messageTemplate,
        scheduledAt: scheduledAt ? new Date(scheduledAt) : undefined,
        segmentCriteria,
      });

      res.status(201).json(campaign);
    } catch (error: any) {
      res.status(500).json({ error: error.message });
    }
  };

  scheduleCampaign = async (req: Request, res: Response) => {
    try {
      const { id } = req.params;
      await this.campaignService.scheduleCampaign(id);

      res.json({ message: 'Campaign scheduled successfully' });
    } catch (error: any) {
      res.status(500).json({ error: error.message });
    }
  };

  getCampaignAnalytics = async (req: Request, res: Response) => {
    try {
      const { id } = req.params;
      const analytics = await this.campaignService.getCampaignAnalytics(id);

      res.json(analytics);
    } catch (error: any) {
      res.status(500).json({ error: error.message });
    }
  };

  listCampaigns = async (req: Request, res: Response) => {
    try {
      const campaignRepo = AppDataSource.getRepository(Campaign);
      const campaigns = await campaignRepo.find({
        order: { createdAt: 'DESC' },
      });

      res.json(campaigns);
    } catch (error: any) {
      res.status(500).json({ error: error.message });
    }
  };
}

import { AppDataSource } from '../config/database';
import { OptOut } from '../entities/OptOut';
import { Contact } from '../entities/Contact';

export class OptOutService {
  private optOutRepo = AppDataSource.getRepository(OptOut);
  private contactRepo = AppDataSource.getRepository(Contact);

  /**
   * Process opt-out request
   * Must be honored immediately per TCPA
   */
  async processOptOut(phoneNumber: string, source: string = 'reply_stop'): Promise<void> {
    // Check if already opted out
    const existing = await this.optOutRepo.findOneBy({ phoneNumber });
    if (existing) {
      return; // Already opted out
    }

    // Create opt-out record
    const optOut = this.optOutRepo.create({
      phoneNumber,
      source,
    });
    await this.optOutRepo.save(optOut);

    // Deactivate contact
    const contact = await this.contactRepo.findOneBy({ phoneNumber });
    if (contact) {
      contact.isActive = false;
      await this.contactRepo.save(contact);
    }

    console.log(`Opt-out processed for ${phoneNumber}`);
  }

  /**
   * Check if phone number is opted out
   */
  async isOptedOut(phoneNumber: string): Promise<boolean> {
    const optOut = await this.optOutRepo.findOneBy({ phoneNumber });
    return !!optOut;
  }

  /**
   * Get all opted-out numbers
   */
  async getAllOptedOutNumbers(): Promise<string[]> {
    const optOuts = await this.optOutRepo.find();
    return optOuts.map(o => o.phoneNumber);
  }
}

import { Request, Response } from 'express';
import { OptOutService } from '../services/OptOutService';
import { PlivoService } from '../services/PlivoService';

export class WebhookController {
  private optOutService = new OptOutService();
  private plivoService = new PlivoService();

  /**
   * Handle inbound SMS messages
   * Automatically process STOP keywords for opt-out
   */
  handleInboundMessage = async (req: Request, res: Response) => {
    try {
      const { From, To, Text } = req.body;

      // Check for opt-out keywords
      const optOutKeywords = ['stop', 'unsubscribe', 'cancel', 'end', 'quit'];
      const messageText = (Text || '').toLowerCase().trim();

      if (optOutKeywords.some(keyword => messageText.includes(keyword))) {
        // Process opt-out
        await this.optOutService.processOptOut(From, 'reply_stop');

        // Send confirmation message (TCPA best practice)
        await this.plivoService.sendSingleMessage(
          From,
          'You have been unsubscribed and will no longer receive messages from us.'
        );

        console.log(`Opt-out processed for ${From}`);
      }

      res.status(200).send('OK');
    } catch (error: any) {
      console.error('Webhook error:', error);
      res.status(500).json({ error: error.message });
    }
  };

  /**
   * Handle delivery status callbacks from Plivo
   */
  handleDeliveryStatus = async (req: Request, res: Response) => {
    try {
      const { MessageUUID, Status, To } = req.body;

      const messageRepo = AppDataSource.getRepository(Message);
      const message = await messageRepo.findOneBy({ plivoMessageUuid: MessageUUID });

      if (message) {
        // Update message status based on Plivo status
        switch (Status) {
          case 'delivered':
            message.status = MessageStatus.DELIVERED;
            message.deliveredAt = new Date();
            break;
          case 'undelivered':
            message.status = MessageStatus.UNDELIVERED;
            break;
          case 'failed':
            message.status = MessageStatus.FAILED;
            break;
        }

        await messageRepo.save(message);

        // Update campaign counters
        const campaignRepo = AppDataSource.getRepository(Campaign);
        const campaign = await campaignRepo.findOneBy({ id: message.campaignId });
        if (campaign && Status === 'delivered') {
          campaign.deliveredCount += 1;
          await campaignRepo.save(campaign);
        }
      }

      res.status(200).send('OK');
    } catch (error: any) {
      console.error('Delivery status error:', error);
      res.status(500).json({ error: error.message });
    }
  };
}

import axios from 'axios';

const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:3000/api',
  headers: {
    'Content-Type': 'application/json',
  },
});

// Campaign API
export const campaignApi = {
  list: () => api.get('/campaigns'),
  get: (id: string) => api.get(`/campaigns/${id}`),
  create: (data: any) => api.post('/campaigns', data),
  schedule: (id: string) => api.post(`/campaigns/${id}/schedule`),
  analytics: (id: string) => api.get(`/campaigns/${id}/analytics`),
};

// Contact API
export const contactApi = {
  list: () => api.get('/contacts'),
  create: (data: any) => api.post('/contacts', data),
  import: (file: File) => {
    const formData = new FormData();
    formData.append('file', file);
    return api.post('/contacts/import', formData, {
      headers: { 'Content-Type': 'multipart/form-data' },
    });
  },
};

export default api;

import React, { useState, useEffect } from 'react';
import { campaignApi } from '../services/api';
import { format } from 'date-fns';

interface Campaign {
  id: string;
  name: string;
  status: string;
  totalRecipients: number;
  sentCount: number;
  deliveredCount: number;
  scheduledAt?: string;
  createdAt: string;
}

export const CampaignDashboard: React.FC = () => {
  const [campaigns, setCampaigns] = useState<Campaign[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    loadCampaigns();
  }, []);

  const loadCampaigns = async () => {
    try {
      const response = await campaignApi.list();
      setCampaigns(response.data);
    } catch (error) {
      console.error('Failed to load campaigns:', error);
    } finally {
      setLoading(false);
    }
  };

  const getStatusColor = (status: string) => {
    const colors = {
      draft: 'bg-gray-200 text-gray-800',
      scheduled: 'bg-blue-200 text-blue-800',
      sending: 'bg-yellow-200 text-yellow-800',
      completed: 'bg-green-200 text-green-800',
      failed: 'bg-red-200 text-red-800',
    };
    return colors[status as keyof typeof colors] || colors.draft;
  };

  if (loading) {
    return <div className="flex justify-center p-8">Loading campaigns...</div>;
  }

  return (
    <div className="max-w-7xl mx-auto p-6">
      <div className="flex justify-between items-center mb-6">
        <h1 className="text-3xl font-bold">SMS Campaigns</h1>
        <button
          onClick={() => window.location.href = '/campaigns/new'}
          className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700"
        >
          Create Campaign
        </button>
      </div>

      <div className="grid gap-4">
        {campaigns.map(campaign => (
          <div key={campaign.id} className="bg-white rounded-lg shadow p-6">
            <div className="flex justify-between items-start mb-4">
              <div>
                <h2 className="text-xl font-semibold">{campaign.name}</h2>
                <p className="text-gray-600 text-sm">
                  Created {format(new Date(campaign.createdAt), 'MMM d, yyyy')}
                </p>
              </div>
              <span className={`px-3 py-1 rounded-full text-sm font-medium ${getStatusColor(campaign.status)}`}>
                {campaign.status}
              </span>
            </div>

            <div className="grid grid-cols-3 gap-4 mb-4">
              <div>
                <p className="text-gray-600 text-sm">Recipients</p>
                <p className="text-2xl font-bold">{campaign.totalRecipients}</p>
              </div>
              <div>
                <p className="text-gray-600 text-sm">Sent</p>
                <p className="text-2xl font-bold">{campaign.sentCount}</p>
              </div>
              <div>
                <p className="text-gray-600 text-sm">Delivered</p>
                <p className="text-2xl font-bold">{campaign.deliveredCount}</p>
              </div>
            </div>

            {campaign.scheduledAt && (
              <p className="text-sm text-gray-600">
                Scheduled for {format(new Date(campaign.scheduledAt), 'MMM d, yyyy h:mm a')}
              </p>
            )}

            <div className="flex gap-2 mt-4">
              <button
                onClick={() => window.location.href = `/campaigns/${campaign.id}`}
                className="text-blue-600 hover:underline"
              >
                View Details
              </button>
              <button
                onClick={() => window.location.href = `/campaigns/${campaign.id}/analytics`}
                className="text-blue-600 hover:underline"
              >
                Analytics
              </button>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
};