Build Scheduled SMS Reminders with Node.js, Express, and Plivo

This guide walks you through building a robust Node.js and Express application to schedule and send SMS appointment reminders using the Plivo communication platform. We'll cover everything from project setup and core logic to deployment and monitoring, creating a production-ready system.

By the end of this tutorial, you will have a fully functional application that enables users (or an admin) to create appointments and automatically sends SMS reminders via Plivo shortly before the scheduled time. This solves the common business need of reducing no-shows and keeping customers informed.

Project Overview and Goals

What we'll build:

• An Express.js web application with API endpoints to create appointments.
• A MongoDB database to store appointment details (name, phone number, time, timezone).
• A background scheduling mechanism using node-cron to periodically check for upcoming appointments.
• Integration with the Plivo SMS API to send reminders to the specified phone numbers.
• Robust error handling, logging, and basic security measures.

Technologies Involved:

• Node.js: A JavaScript runtime for building the backend server.
• Express.js: A minimal and flexible Node.js web application framework for creating the API.
• MongoDB: A NoSQL database for storing appointment data. We'll use Mongoose as the ODM (Object Data Modeling) library.
• Plivo: A cloud communications platform providing SMS APIs. We'll use their Node.js SDK.
• node-cron: A simple cron-like job scheduler for Node.js.
• dotenv: To manage environment variables securely.
• winston: For robust logging.
• express-validator: For request validation.
• cors: To enable Cross-Origin Resource Sharing.
• express-rate-limit: To protect against brute-force attacks.
• luxon: For robust timezone validation.
• date-fns: For date formatting.
• date-fns-tz: For timezone conversions.

Why these technologies?

• Node.js and Express provide a fast, scalable, and widely-used foundation for building APIs.
• MongoDB offers flexibility for storing appointment data, and Mongoose simplifies interactions.
• Plivo provides reliable SMS delivery APIs with clear documentation and a helpful Node.js SDK.
• node-cron is straightforward for implementing background scheduling tasks within the Node.js application itself.

System Architecture:

graph LR
    A[Client/Admin UI] -- HTTP POST --> B(Express API);
    B -- Create Appointment --> C{MongoDB Database};
    D(Node Cron Scheduler) -- Runs Every Minute --> E{Reminder Service};
    E -- Check Upcoming Appointments --> C;
    E -- Found Appointment --> F(Plivo Service);
    F -- Send SMS --> G((Plivo API));
    G -- SMS Delivered --> H(User's Phone);

    subgraph Node.js/Express Application
        B
        D
        E
        F
    end

    style C fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#ccf,stroke:#333,stroke-width:2px

(Note: Mermaid diagram rendering depends on the Markdown platform.)

Prerequisites:

• Node.js (v16 or later recommended) and npm/yarn installed.
• Access to a MongoDB instance (local installation or a cloud service like MongoDB Atlas).
• A Plivo account (free trial available).
• A Plivo phone number capable of sending SMS messages.
• Basic understanding of JavaScript, Node.js, Express, and REST APIs.
• A code editor (like VS Code).
• A tool for testing APIs (like Postman or curl).

1. Setting up the Project

Let's initialize the project, install dependencies, and set up the basic structure.

1. Create Project Directory:

   bashCopy

   mkdir plivo-scheduler-app
   cd plivo-scheduler-app

2. Initialize Node.js Project:

   bashCopy

   npm init -y

   This creates a package.json file.

3. Install Dependencies:

   bashCopy

   npm install express mongoose plivo node-cron dotenv winston express-validator cors express-rate-limit luxon date-fns date-fns-tz

   • express: Web framework.
   • mongoose: MongoDB ODM.
   • plivo: Plivo Node.js SDK.
   • node-cron: Job scheduler.
   • dotenv: Environment variable loader.
   • winston: Logger.
   • express-validator: Input validation middleware.
   • cors: Enable CORS.
   • express-rate-limit: API rate limiting.
   • luxon: Timezone validation.
   • date-fns: Date formatting.
   • date-fns-tz: Timezone conversion.

4. Install Development Dependencies (Optional but Recommended):

   bashCopy

   npm install --save-dev nodemon jest supertest

   • nodemon: Automatically restarts the server during development.
   • jest: Testing framework.
   • supertest: HTTP assertion library for testing API endpoints.

5. Configure nodemon (Optional): Add a dev script to your package.json:

   jsonCopy

   // package.json
   {
     // ... other fields
     ""scripts"": {
       ""start"": ""node server.js"",
       ""dev"": ""nodemon server.js"",
       ""test"": ""jest""
     },
     // ... other fields
   }

   Now you can run npm run dev to start the server with auto-reloading.

6. Create Environment File: Create a file named .env in the project root. Never commit this file to version control.

   dotenvCopy

   # .env
   PORT=5000
   MONGO_URI=mongodb://localhost:27017/plivoScheduler # Replace with your MongoDB connection string
   PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
   PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
   PLIVO_PHONE_NUMBER=+1XXXXXXXXXX # Your Plivo phone number in E.164 format

   • PORT: The port your Express server will listen on.
   • MONGO_URI: Your MongoDB connection string.
   • PLIVO_AUTH_ID & PLIVO_AUTH_TOKEN: Found on your Plivo Console dashboard. Go to Account -> Overview after logging in.
   • PLIVO_PHONE_NUMBER: A Plivo phone number you own, enabled for SMS, in E.164 format (e.g., +14155551212). You can purchase one under Phone Numbers -> Buy Numbers in the Plivo console.

7. Create .gitignore File: Create a .gitignore file in the root to prevent sensitive files and unnecessary directories from being committed.

   textCopy

   # .gitignore
   node_modules/
   .env
   npm-debug.log
   *.log

8. Set Up Project Structure: Create the following directories for better organization:

   plivo-scheduler-app/ ├── config/ # Configuration files (DB, logger) ├── controllers/ # Request handlers ├── models/ # Mongoose models/schemas ├── routes/ # Express route definitions ├── services/ # Business logic (Plivo, scheduling) ├── utils/ # Utility functions ├── logs/ # Log files (ensure this exists or winston might error) ├── tests/ # Test files ├── .env ├── .gitignore ├── package.json └── server.js # Main application entry point

   Create an empty file inside logs/ like .gitkeep if you want Git to track the empty directory.

9. Create Initial Server File (server.js):

   javascriptCopy

   // server.js
   require('dotenv').config(); // Load environment variables first
   const express = require('express');
   const cors = require('cors');
   const connectDB = require('./config/db');
   const logger = require('./config/logger');
   const appointmentRoutes = require('./routes/appointments');
   const errorHandler = require('./utils/errorHandler');
   const startScheduler = require('./services/scheduler');
   
   // Connect to Database
   connectDB();
   
   const app = express();
   
   // --- Middleware ---
   // Enable CORS for all origins (adjust for production)
   app.use(cors());
   
   // Body Parser Middleware
   app.use(express.json());
   app.use(express.urlencoded({ extended: false }));
   
   // Logging Middleware (Example: Log requests)
   app.use((req, res, next) => {
     logger.info(`${req.method} ${req.originalUrl}`, { ip: req.ip });
     next();
   });
   
   // --- API Routes ---
   app.use('/api/appointments', appointmentRoutes);
   
   // Simple Health Check Endpoint
   app.get('/health', (req, res) => res.status(200).send('OK'));
   
   // --- Error Handling Middleware ---
   // Should be loaded after routes
   // Assuming errorHandler is defined in './utils/errorHandler.js'
   // Example basic error handler if not defined elsewhere:
   // app.use((err, req, res, next) => {
   //   logger.error(err.message, { stack: err.stack });
   //   res.status(err.statusCode || 500).json({
   //     success: false,
   //     error: err.message || 'Server Error'
   //   });
   // });
   // Replace the above comment with:
   app.use(errorHandler);
   
   
   const PORT = process.env.PORT || 5000;
   
   const server = app.listen(PORT, () => { // Store server instance
     logger.info(`Server running in ${process.env.NODE_ENV || 'development'} mode on port ${PORT}`);
     // Start the scheduler after the server starts
     startScheduler();
     logger.info('Reminder scheduler started.');
   });
   
   // Handle unhandled promise rejections
   process.on('unhandledRejection', (err, promise) => {
     logger.error(`Unhandled Rejection: ${err.message}`, { stack: err.stack });
     // Optionally close server gracefully
     // server.close(() => process.exit(1));
   });
   
   // Handle uncaught exceptions
   process.on('uncaughtException', (err) => {
     logger.error(`Uncaught Exception: ${err.message}`, { stack: err.stack });
     // Optionally close server gracefully
     // server.close(() => process.exit(1));
   });

2. Implementing Core Functionality

Now, let's build the scheduling and reminder sending logic.

1. Create Logger Configuration (config/logger.js):

   javascriptCopy

   // config/logger.js
   const winston = require('winston');
   const path = require('path');
   
   const logFormat = winston.format.printf(({ level, message, timestamp, stack, ...metadata }) => {
     let log = `${timestamp} [${level}]: ${message}`;
     // Add metadata if present
     if (metadata && Object.keys(metadata).length > 0) {
       log += ` ${JSON.stringify(metadata)}`;
     }
     // Add stack trace for errors
     if (stack) {
       log += `\nStack: ${stack}`;
     }
     return log;
   });
   
   const logger = winston.createLogger({
     level: process.env.LOG_LEVEL || 'info',
     format: winston.format.combine(
       winston.format.colorize(),
       winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
       winston.format.errors({ stack: true }), // Log stack traces
       logFormat
     ),
     transports: [
       // Console transport
       new winston.transports.Console(),
       // File transport for all logs
       new winston.transports.File({
         filename: path.join('logs', 'app.log'),
         level: 'info',
         format: winston.format.combine(
           winston.format.uncolorize(), // Don't write color codes to file
           winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
           winston.format.errors({ stack: true }),
           logFormat
         ),
       }),
       // File transport for error logs
       new winston.transports.File({
         filename: path.join('logs', 'error.log'),
         level: 'error',
         format: winston.format.combine(
           winston.format.uncolorize(),
           winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
           winston.format.errors({ stack: true }),
           logFormat
         ),
       }),
     ],
     exceptionHandlers: [ // Catch unhandled exceptions
       new winston.transports.File({ filename: path.join('logs', 'exceptions.log') })
     ],
     rejectionHandlers: [ // Catch unhandled promise rejections
       new winston.transports.File({ filename: path.join('logs', 'rejections.log') })
     ]
   });
   
   module.exports = logger;

   Why Winston? It provides flexible logging with multiple transports (console, file), levels, and formatting, essential for production monitoring.

2. Create Plivo Service (services/plivoService.js): This service encapsulates interaction with the Plivo API.

   javascriptCopy

   // services/plivoService.js
   const plivo = require('plivo');
   const logger = require('../config/logger');
   
   const client = new plivo.Client(process.env.PLIVO_AUTH_ID, process.env.PLIVO_AUTH_TOKEN);
   
   /**
    * Sends an SMS reminder using Plivo.
    * @param {string} toPhoneNumber - Recipient phone number in E.164 format.
    * @param {string} messageBody - The text message content.
    * @returns {Promise<object>} Plivo API response.
    * @throws {Error} If sending fails or inputs are invalid.
    */
   const sendSmsReminder = async (toPhoneNumber, messageBody) => {
     // Basic validation (more robust validation in API layer)
     if (!toPhoneNumber || !messageBody) {
       throw new Error('Recipient phone number and message body are required.');
     }
     // Strict E.164 format check before sending to Plivo
     if (!/^\+[1-9]\d{1,14}$/.test(toPhoneNumber)) {
        throw new Error(`Invalid E.164 format for recipient phone number: ${toPhoneNumber}`);
     }
   
     logger.info(`Attempting to send SMS to ${toPhoneNumber}`);
   
     try {
       const response = await client.messages.create(
         process.env.PLIVO_PHONE_NUMBER, // Sender (Your Plivo Number)
         toPhoneNumber,                  // Recipient
         messageBody                     // Message Text
         // Optional params can go here, e.g., { url: 'callback_url' } for status updates
       );
   
       // Plivo returns message_uuid in an array
       const messageUuid = response.messageUuid && response.messageUuid.length > 0 ? response.messageUuid[0] : 'N/A';
       logger.info(`SMS sent successfully to ${toPhoneNumber}. Message UUID: ${messageUuid}`);
       return response;
     } catch (error) {
       logger.error(`Failed to send SMS to ${toPhoneNumber}. Error: ${error.message}`, {
         plivoError: error.response ? error.response.data : 'N/A', // Log Plivo specific error if available
         stack: error.stack,
       });
       // Re-throw the error to be handled by the calling function (scheduler)
       throw error;
     }
   };
   
   module.exports = {
     sendSmsReminder,
   };

   Why a separate service? It isolates Plivo-specific logic, making the code modular and easier to test or swap providers later. We include E.164 validation and throw errors for consistency.

3. Create Reminder Service (services/reminderService.js): This service contains the logic for finding due appointments and triggering the SMS.

   javascriptCopy

   // services/reminderService.js
   const Appointment = require('../models/Appointment');
   const plivoService = require('./plivoService');
   const logger = require('../config/logger');
   const { format } = require('date-fns'); // Using date-fns for reliable date formatting
   
   // How many minutes before the appointment to send the reminder
   const REMINDER_WINDOW_MINUTES = 15;
   
   /**
    * Finds appointments due for reminders and sends SMS via Plivo.
    */
   const checkAndSendReminders = async () => {
     logger.info('Scheduler checking for appointments needing reminders...');
   
     const now = new Date();
     // Calculate the time window [now, now + REMINDER_WINDOW_MINUTES]
     const reminderCutoffTime = new Date(now.getTime() + REMINDER_WINDOW_MINUTES * 60 * 1000);
   
     try {
       // Find appointments within the window that haven't had a notification sent
       // Assumes appointment.time is stored in UTC
       const appointmentsToRemind = await Appointment.find({
         time: {
           $gte: now, // Appointment time is now or in the future
           $lte: reminderCutoffTime, // Appointment time is within the next N minutes
         },
         notificationSent: false, // Reminder not yet sent
       }).exec(); // Use exec() for cleaner promise handling
   
       if (appointmentsToRemind.length === 0) {
         logger.info('No appointments found requiring reminders in this cycle.');
         return;
       }
   
       logger.info(`Found ${appointmentsToRemind.length} appointments to remind.`);
   
       for (const appointment of appointmentsToRemind) {
         try {
           // Format time for the message - consider appointment's timezone if stored
           // For simplicity here, we format based on server time (UTC) - add timezone logic if needed
           // Ensure appointment.time is a valid Date object before formatting
           const appointmentDate = new Date(appointment.time);
           if (isNaN(appointmentDate.getTime())) {
               logger.error(`Invalid date format for appointment ID ${appointment._id}: ${appointment.time}`);
               continue; // Skip this appointment
           }
           // Example format: ""4:30 PM on December 25, 2024""
           const formattedTime = format(appointmentDate, ""h:mm a 'on' MMMM d, yyyy"");
           const messageBody = `Hi ${appointment.name}, this is a reminder for your appointment scheduled at ${formattedTime}. See you soon!`;
   
           await plivoService.sendSmsReminder(appointment.phoneNumber, messageBody);
   
           // Mark the appointment as notified IN THE DATABASE
           appointment.notificationSent = true;
           await appointment.save();
           logger.info(`Successfully processed reminder for appointment ID: ${appointment._id}`);
   
         } catch (error) {
           // Log error for this specific appointment but continue with others
           logger.error(`Error processing reminder for appointment ID ${appointment._id}: ${error.message}`, { stack: error.stack });
           // Optional: Implement retry logic here or flag for manual review
           // For example, add a field like `notificationFailedAttempts`
           // appointment.notificationFailedAttempts = (appointment.notificationFailedAttempts || 0) + 1;
           // await appointment.save();
         }
       }
       logger.info('Finished processing reminders for this cycle.');
   
     } catch (dbError) {
       logger.error(`Database error while fetching appointments: ${dbError.message}`, { stack: dbError.stack });
     }
   };
   
   module.exports = {
     checkAndSendReminders,
   };

   Key Logic: It queries MongoDB for appointments where the time is between now and now + REMINDER_WINDOW_MINUTES and notificationSent is false. It then iterates, sends the SMS via plivoService, and crucially updates notificationSent to true to prevent duplicate messages. Error handling is included for both DB queries and individual SMS sends. Correct date formatting string is used.

4. Create Scheduler (services/scheduler.js): This sets up the node-cron job.

   javascriptCopy

   // services/scheduler.js
   const cron = require('node-cron');
   const { checkAndSendReminders } = require('./reminderService');
   const logger = require('../config/logger');
   
   let task = null;
   
   const startScheduler = () => {
     // Schedule to run every minute ('*/1 * * * *')
     // You can adjust the schedule as needed (e.g., '*/5 * * * *' for every 5 minutes)
     // See https://crontab.guru/ for cron syntax help
     if (task) {
        logger.warn('Scheduler already running.');
        return;
     }
   
     logger.info('Initializing cron scheduler...');
     task = cron.schedule('*/1 * * * *', async () => {
       logger.info('Cron job triggered: Running checkAndSendReminders...');
       try {
         await checkAndSendReminders();
       } catch (error) {
         // Catch potential top-level errors from checkAndSendReminders itself
         logger.error(`Unhandled error during cron job execution: ${error.message}`, { stack: error.stack });
       }
     }, {
       scheduled: true,
       timezone: ""UTC"" // IMPORTANT: Run scheduler logic in UTC to avoid DST issues
                      // Ensure appointment times are also consistently handled (e.g., stored in UTC)
     });
   
     logger.info(`Scheduler task started. Will run every minute.`);
   
     task.start(); // Explicitly start the task
   };
   
   const stopScheduler = () => {
       if (task) {
           task.stop();
           task = null;
           logger.info('Scheduler task stopped.');
       } else {
           logger.warn('Scheduler task was not running.');
       }
   };
   
   
   module.exports = startScheduler; // Export the start function
   // Optionally export stopScheduler if needed elsewhere:
   // module.exports = { startScheduler, stopScheduler };

   Why node-cron? It's simple and integrates directly into the Node application. The schedule '*/1 * * * *' means ""run every minute"". Setting the timezone to UTC is crucial for consistency.

3. Building a Complete API Layer

We need an endpoint to create appointments.

1. Create Appointment Model (models/Appointment.js):

   javascriptCopy

   // models/Appointment.js
   const mongoose = require('mongoose');
   
   const AppointmentSchema = new mongoose.Schema({
     name: {
       type: String,
       required: [true, 'Customer name is required.'],
       trim: true,
     },
     phoneNumber: {
       type: String,
       required: [true, 'Phone number is required.'],
       trim: true,
       // Basic validation for E.164 format - more strict validation can be added
       match: [/^\+[1-9]\d{1,14}$/, 'Phone number must be in E.164 format (e.g., +14155551212).'],
     },
     time: {
       type: Date,
       required: [true, 'Appointment time is required.'],
       index: true, // Index for faster querying
     },
     timeZone: { // Store the original timezone for potential display purposes
       type: String,
       required: [true, 'Timezone is required (e.g., America/New_York).'],
       trim: true,
     },
     notificationSent: {
       type: Boolean,
       default: false,
       index: true, // Index for faster querying by the scheduler
     },
     // Optional: Track reminder failures
     // notificationFailedAttempts: {
     //   type: Number,
     //   default: 0
     // },
     createdAt: {
       type: Date,
       default: Date.now,
     },
   });
   
   // Ensure indexes are created
   AppointmentSchema.index({ time: 1, notificationSent: 1 });
   
   module.exports = mongoose.model('Appointment', AppointmentSchema);

   Schema Design: Includes necessary fields, basic validation, default values, and crucially, indexes on time and notificationSent for efficient querying by the scheduler. Storing timeZone is good practice, even if the time itself is stored in UTC.

2. Create Database Connection (config/db.js):

   javascriptCopy

   // config/db.js
   const mongoose = require('mongoose');
   const logger = require('./logger');
   
   const connectDB = async () => {
     try {
       // Starting from Mongoose v6, options are no longer needed for basic connections
       const conn = await mongoose.connect(process.env.MONGO_URI);
   
       logger.info(`MongoDB Connected: ${conn.connection.host}`);
     } catch (err) {
       logger.error(`MongoDB Connection Error: ${err.message}`, { stack: err.stack });
       // Exit process with failure
       process.exit(1);
     }
   };
   
   module.exports = connectDB;

3. Create Appointment Controller (controllers/appointmentController.js):

   javascriptCopy

   // controllers/appointmentController.js
   const Appointment = require('../models/Appointment');
   const logger = require('../config/logger');
   const { validationResult } = require('express-validator');
   const { zonedTimeToUtc } = require('date-fns-tz'); // For handling timezones correctly
   
   /**
    * @desc    Create a new appointment
    * @route   POST /api/appointments
    * @access  Public (Add auth middleware later if needed)
    */
   exports.createAppointment = async (req, res, next) => {
     // 1. Validation
     const errors = validationResult(req);
     if (!errors.isEmpty()) {
       logger.warn('Validation failed for createAppointment', { errors: errors.array() });
       return res.status(400).json({ errors: errors.array() });
     }
   
     const { name, phoneNumber, time, timeZone } = req.body;
   
     try {
       // 2. Convert scheduled time to UTC for storage
       // We expect 'time' to be a string like '2025-12-25T14:30:00'
       // We use the provided timeZone to interpret this local time correctly
       let appointmentTimeUTC;
       try {
           // Ensure the input time string is treated as local time in the specified zone
           appointmentTimeUTC = zonedTimeToUtc(time, timeZone);
       } catch (tzError) {
           logger.warn(`Invalid time or timezone provided: ${time}, ${timeZone}`, { error: tzError.message });
           return res.status(400).json({ errors: [{ msg: 'Invalid time or timezone format. Use ISO 8601 format for time (YYYY-MM-DDTHH:mm:ss) and IANA timezone names (e.g., America/New_York).' }] });
       }
   
       // Ensure the appointment time is in the future
       if (appointmentTimeUTC <= new Date()) {
            logger.warn(`Attempt to schedule appointment in the past: ${appointmentTimeUTC}`);
            return res.status(400).json({ errors: [{ msg: 'Appointment time must be in the future.' }] });
       }
   
   
       // 3. Create new appointment instance
       const newAppointment = new Appointment({
         name,
         phoneNumber, // Already validated for E.164 in model/validator
         time: appointmentTimeUTC, // Store UTC time
         timeZone, // Store original timezone
       });
   
       // 4. Save to database
       const savedAppointment = await newAppointment.save();
   
       logger.info(`Appointment created successfully: ${savedAppointment._id}`, { name, time: savedAppointment.time });
       res.status(201).json({
         success: true,
         message: 'Appointment created successfully.',
         data: savedAppointment,
       });
   
     } catch (error) {
       // Pass error to the global error handler
       logger.error(`Error creating appointment: ${error.message}`, { stack: error.stack });
       next(error); // Pass to centralized error handler
     }
   };
   
   /**
    * @desc    Get all appointments (Optional - for testing/admin)
    * @route   GET /api/appointments
    * @access  Public (Add auth middleware later if needed)
    */
   exports.getAppointments = async (req, res, next) => {
       try {
           const appointments = await Appointment.find().sort({ time: 1 }); // Sort by time
           res.status(200).json({
               success: true,
               count: appointments.length,
               data: appointments
           });
       } catch (error) {
           logger.error(`Error fetching appointments: ${error.message}`, { stack: error.stack });
           next(error);
       }
   };

   Important: This controller handles validation results, converts the incoming local time + timezone into UTC using date-fns-tz before saving, and ensures appointments are scheduled for the future.

4. Create Appointment Routes (routes/appointments.js):

   javascriptCopy

   // routes/appointments.js
   const express = require('express');
   const { body } = require('express-validator');
   const { createAppointment, getAppointments } = require('../controllers/appointmentController');
   const validateTimeZone = require('../utils/validateTimeZone'); // Custom validator
   
   const router = express.Router();
   
   // Validation middleware for creating an appointment
   const createAppointmentValidation = [
     body('name', 'Name is required').not().isEmpty().trim().escape(),
     body('phoneNumber', 'Valid E.164 phone number is required (e.g., +14155551212)').matches(/^\+[1-9]\d{1,14}$/),
     // Use isISO8601({ strict: true, strictSeparator: true }) for stricter format YYYY-MM-DDTHH:mm:ss
     body('time', 'Appointment time is required in ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ss)').isISO8601({ strict: true, strictSeparator: true }).withMessage('Use format YYYY-MM-DDTHH:mm:ss for time'),
     // Use custom validator for timezone
     body('timeZone').custom(validateTimeZone),
   ];
   
   // POST /api/appointments - Create a new appointment
   router.post('/', createAppointmentValidation, createAppointment);
   
   // GET /api/appointments - Get all appointments (optional)
   router.get('/', getAppointments);
   
   
   module.exports = router;

   Validation: Uses express-validator to check incoming request bodies for required fields and correct formats before the data reaches the controller. Includes stricter ISO8601 check and a custom timezone validator.

5. Create Timezone Validator (utils/validateTimeZone.js): We need a way to check if the provided timezone string is valid.

   javascriptCopy

   // utils/validateTimeZone.js
   const { DateTime } = require('luxon'); // Luxon is good for timezone validation
   
   const validateTimeZone = (value) => {
     if (!value) {
       throw new Error('Timezone is required.');
     }
     // Check if the timezone identifier is valid according to Luxon/IANA db
     if (!DateTime.local().setZone(value).isValid) {
         throw new Error(`Invalid IANA timezone identifier: '${value}'. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones`);
     }
     // If valid, return true for express-validator
     return true;
   };
   
   module.exports = validateTimeZone;

   Why Luxon? Luxon has a robust way (setZone().isValid) to check if an IANA timezone string is recognized.

6. Test API Endpoint: Use curl or Postman to test the POST /api/appointments endpoint.

   curl Example:

   bashCopy

   # Note: Ensure time format matches YYYY-MM-DDTHH:mm:ss exactly
   curl -X POST http://localhost:5000/api/appointments \
   -H ""Content-Type: application/json"" \
   -d '{
     ""name"": ""Alice Test"",
     ""phoneNumber"": ""+14155551212"",
     ""time"": ""2025-12-24T10:00:00"",
     ""timeZone"": ""America/Los_Angeles""
   }'

   Expected JSON Response (Success - 201 Created):

   jsonCopy

   {
     ""success"": true,
     ""message"": ""Appointment created successfully."",
     ""data"": {
       ""name"": ""Alice Test"",
       ""phoneNumber"": ""+14155551212"",
       ""time"": ""2025-12-24T18:00:00.000Z"",
       ""timeZone"": ""America/Los_Angeles"",
       ""notificationSent"": false,
       ""_id"": ""someGeneratedMongoId"",
       ""createdAt"": ""2025-04-20T..."",
       ""__v"": 0
     }
   }

   Expected JSON Response (Validation Error - 400 Bad Request):

   jsonCopy

   {
     ""errors"": [
       {
         ""type"": ""field"",
         ""value"": ""2025-12-24 10:00"",
         ""msg"": ""Use format YYYY-MM-DDTHH:mm:ss for time"",
         ""path"": ""time"",
         ""location"": ""body""
       }
     ]
   }

4. Integrating with Plivo (Review)

We've already set up the Plivo integration within services/plivoService.js. Key aspects:

• Configuration: PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, and PLIVO_PHONE_NUMBER are securely loaded from .env.
• SDK Initialization: The Plivo client is initialized once when the service module loads.
• Sending SMS: The sendSmsReminder function handles the API call (client.messages.create) with necessary parameters (src, dst, text). Note: Plivo SDK uses src for sender and dst for recipient.
• Secrets Handling: API credentials are kept out of the codebase using environment variables via dotenv.

Obtaining Plivo Credentials:

1. Log in to your Plivo Console (https://console.plivo.com/).
2. On the main Dashboard (Overview page), you will find your Auth ID and Auth Token. Click the ""Show"" icon if needed.
   • PLIVO_AUTH_ID: Copy the value labelled ""Auth ID"".
   • PLIVO_AUTH_TOKEN: Copy the value labelled ""Auth Token"".
3. Navigate to Phone Numbers -> Your Numbers.
   • PLIVO_PHONE_NUMBER: Copy one of your Plivo numbers that is SMS-enabled. Ensure it's in the E.164 format (e.g., +14155551212). If you don't have one, go to Phone Numbers -> Buy Numbers.

5. Implementing Error Handling, Logging, and Retries

• Error Handling Strategy:
  • Validation errors are caught early by express-validator in routes and returned as 400 responses.
  • Controller errors (DB issues, unexpected problems) are caught in try...catch blocks and passed to a centralized error handler using next(error).
  • Service-level errors (e.g., Plivo API failure in plivoService, DB errors in reminderService) are logged within the service and re-thrown to be handled by the caller (e.g., the scheduler or controller).
  • Unhandled promise rejections and uncaught exceptions are caught globally in server.js and logged using Winston.
• Logging:
  • Winston is configured (config/logger.js) to log to the console and separate files (app.log, error.log, exceptions.log, rejections.log).
  • Logs include timestamps, levels, messages, metadata, and stack traces for errors.
  • Key events like server start, scheduler activity, appointment creation, SMS sending attempts, and errors are logged.
• Retries (Conceptual):
  • Database Operations: Mongoose connection logic includes basic retry/exit on initial failure. For specific operations, libraries like async-retry could be used within controllers/services if needed.
  • Plivo SMS Sending: The current plivoService logs errors but doesn't automatically retry. For higher reliability:
    1. Modify plivoService or reminderService to catch Plivo errors specifically.
    2. Implement a retry mechanism (e.g., using async-retry or a simple loop with delays) for transient network errors or specific Plivo error codes.
    3. Consider adding a field like notificationFailedAttempts to the Appointment model. Increment this on failure.
    4. Update the scheduler query to potentially retry appointments with notificationFailedAttempts < MAX_RETRIES.
    5. After max retries, flag the appointment for manual review or stop retrying.
  • Scheduler Job: node-cron itself doesn't handle job failures. The try...catch block within the scheduled task in services/scheduler.js ensures that an error during one run doesn't crash the entire scheduler process.

(Further sections like Deployment, Security, Testing, and Conclusion would typically follow here but were not included in the provided input text.)