Build a Node.js Appointment Scheduler with SMS Reminders

System Flow:

[User/Client] --(HTTP POST /appointments)--> [Express API Server]
    |
    +----(Create Appointment)----> [MongoDB Database]
    +----(Read/Write Data)------> [MongoDB Database]

[Background Scheduler (node-cron)] --(Periodically Checks)--> [MongoDB Database]
    |
    +----(Finds Upcoming Appointment)--> [Plivo Service]
    |                                    |
    |                                    +--(Send SMS Request)--> [Plivo API]
    |                                                             |
    |                                                             +--(Sends SMS)--> [User's Phone]
    +----(Update Reminder Status)-----> [MongoDB Database]

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

npm init -y

npm install express mongoose plivo node-cron dotenv

npm install --save-dev nodemon

// package.json
{
  // ... other properties
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  // ... other properties
}

# .env

# Plivo Credentials
# Get these from your Plivo Console: https://console.plivo.com/dashboard/
PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
PLIVO_PHONE_NUMBER=+1XXXXXXXXXX # Your Plivo SMS-enabled number in E.164 format

# MongoDB Connection
MONGO_URI=mongodb://localhost:27017/appointment_scheduler # Replace with your MongoDB connection string

# Application Settings
PORT=3000
REMINDER_MINUTES_BEFORE=60 # Send reminder 60 minutes before appointment
CRON_SCHEDULE=* * * * * # Run scheduler check every minute

# .gitignore

# Dependencies
node_modules/

# Environment variables
.env

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# OS generated files
.DS_Store
Thumbs.db

// server.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const connectDB = require('./config/db');
const appointmentRoutes = require('./routes/appointments');
const { startScheduler } = require('./services/scheduler');
const mongoose = require('mongoose'); // Needed for health check later

const app = express();

// Connect to Database
connectDB();

// Init Middleware
app.use(express.json()); // Enable parsing JSON request bodies

// Define Routes
app.get('/', (req, res) => res.send('Appointment Scheduler API Running'));
app.use('/api/appointments', appointmentRoutes); // Mount appointment routes

// Health Check Endpoint (Example)
app.get('/healthz', async (req, res) => {
  try {
    // Check database connection status (Mongoose connection state)
    const dbState = mongoose.connection.readyState;
    // 0: disconnected; 1: connected; 2: connecting; 3: disconnecting
    if (dbState === 1) {
       res.status(200).send('OK');
    } else {
       throw new Error(`DB not connected. State: ${dbState}`);
    }
  } catch (error) {
    console.error("Health check failed:", error.message);
    res.status(503).send('Service Unavailable');
  }
});


const PORT = process.env.PORT || 3000;

// Basic Error Handling (Example - Enhance as needed)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

// Start server only if not in test environment (to allow Supertest to bind port)
// And export app for testing purposes
if (process.env.NODE_ENV !== 'test') {
    app.listen(PORT, () => {
      console.log(`Server started on port ${PORT}`);
      // Start the reminder scheduler after the server starts
      startScheduler();
    });
}

module.exports = app; // Export the app instance for testing

// config/db.js
const mongoose = require('mongoose');

const connectDB = async () => {
  try {
    // Mongoose 6+ requires MONGO_URI to be defined
    if (!process.env.MONGO_URI) {
        throw new Error('MONGO_URI is not defined in environment variables.');
    }
    await mongoose.connect(process.env.MONGO_URI, {
      // Mongoose 6+ uses these defaults, but explicit for clarity
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log('MongoDB Connected...');
  } catch (err) {
    console.error('MongoDB Connection Error:', err.message);
    // Exit process with failure
    process.exit(1);
  }
};

module.exports = connectDB;

npm run dev # Uses nodemon if installed
# or
npm start   # Uses node directly

// models/Appointment.js
const mongoose = require('mongoose');

const AppointmentSchema = new mongoose.Schema({
  name: {
    type: String,
    required: [true, 'Patient name is required.'],
    trim: true,
  },
  phoneNumber: {
    type: String,
    required: [true, 'Phone number is required.'],
    // Example: Very basic check for '+' prefix and digits. Doesn't enforce length or full E.164 rules.
    // Use a library like `google-libphonenumber` for production validation.
    validate: {
      validator: function(v) {
        return /^\+\d+$/.test(v);
      },
      message: props => `${props.value} is not a valid phone number format (must start with + and contain digits). Use E.164 format.`
    },
  },
  appointmentTime: {
    type: Date,
    required: [true, 'Appointment time is required.'],
  },
  timeZone: {
    type: String,
    required: [true, 'Time zone is required (e.g., America/New_York).'], // Store the original time zone
  },
  reminderSent: {
    type: Boolean,
    default: false, // Track if a reminder has been sent
  },
}, { timestamps: true }); // Enable timestamps

// Index appointmentTime for faster querying by the scheduler
AppointmentSchema.index({ appointmentTime: 1, reminderSent: 1 });

module.exports = mongoose.model('Appointment', AppointmentSchema);

// controllers/appointmentController.js
const Appointment = require('../models/Appointment');

// @desc    Create a new appointment
// @route   POST /api/appointments
// @access  Public (Add auth later if needed)
exports.createAppointment = async (req, res, next) => {
  try {
    const { name, phoneNumber, appointmentTime, timeZone } = req.body;

    // Input validation should ideally be handled by middleware (e.g., express-validator).
    // Basic checks can remain as a fallback if needed.
    // if (!name || !phoneNumber || !appointmentTime || !timeZone) {
    //   return res.status(400).json({ success: false, message: 'Missing required fields.' });
    // }

    // Create appointment (Mongoose handles Date conversion if string is ISO 8601 format)
    const newAppointment = await Appointment.create({
      name,
      phoneNumber,
      appointmentTime, // Expecting ISO 8601 format string e.g., ""2025-12-31T14:30:00.000Z"" or a JS Date object
      timeZone,
      reminderSent: false // Explicitly set, though it's the default
    });

    console.log(`Appointment created: ${newAppointment._id} for ${newAppointment.name} at ${newAppointment.appointmentTime}`);

    res.status(201).json({
      success: true,
      data: newAppointment,
      message: 'Appointment scheduled successfully.'
    });

  } catch (error) {
    console.error('Error creating appointment:', error);
    // Handle Mongoose validation errors specifically
    if (error.name === 'ValidationError') {
        const messages = Object.values(error.errors).map(val => val.message);
        return res.status(400).json({ success: false, message: messages.join(', ') });
    }
    // Generic error handling
    res.status(500).json({ success: false, message: 'Server error creating appointment.' });
    // Optional: pass error to a global error handler `next(error)`
  }
};

// @desc    Get all appointments (Example - add filtering/pagination for production)
// @route   GET /api/appointments
// @access  Public (Add auth later if needed)
exports.getAppointments = async (req, res, next) => {
    try {
        // Example: Add basic pagination
        const page = parseInt(req.query.page, 10) || 1;
        const limit = parseInt(req.query.limit, 10) || 10;
        const skip = (page - 1) * limit;

        const appointments = await Appointment.find()
            .sort({ appointmentTime: 1 }) // Sort by date
            .skip(skip)
            .limit(limit);

        const totalAppointments = await Appointment.countDocuments(); // Get total count for pagination info

        res.status(200).json({
            success: true,
            count: appointments.length,
            pagination: {
                currentPage: page,
                totalPages: Math.ceil(totalAppointments / limit),
                totalItems: totalAppointments
            },
            data: appointments
        });
    } catch (error) {
        console.error('Error fetching appointments:', error);
        res.status(500).json({ success: false, message: 'Server error fetching appointments.' });
    }
};

// Add functions for getting single appointment, updating, deleting as needed

// routes/appointments.js
const express = require('express');
const { createAppointment, getAppointments } = require('../controllers/appointmentController');
// We will add validation middleware here later (e.g., using express-validator)
// const { validateAppointment } = require('../middleware/validator');

const router = express.Router();

// Route for creating an appointment
// Apply validation middleware before the controller (example shown, implement later)
// router.post('/', validateAppointment, createAppointment);
router.post('/', createAppointment); // Currently without validation middleware

// Route for getting all appointments
router.get('/', getAppointments);

// Add routes for GET /:id, PUT /:id, DELETE /:id as needed

module.exports = router;

curl -X POST http://localhost:3000/api/appointments \
-H "Content-Type: application/json" \
-d '{
    "name": "Alice Smith",
    "phoneNumber": "+15551234567",
    "appointmentTime": "2025-12-25T15:00:00.000Z",
    "timeZone": "America/New_York"
}'

{
    "success": true,
    "data": {
        "name": "Alice Smith",
        "phoneNumber": "+15551234567",
        "appointmentTime": "2025-12-25T15:00:00.000Z",
        "timeZone": "America/New_York",
        "reminderSent": false,
        "_id": "someGeneratedMongoId",
        "createdAt": "...",
        "updatedAt": "..."
    },
    "message": "Appointment scheduled successfully."
}

// services/plivoService.js
const plivo = require('plivo');
require('dotenv').config(); // Ensure env vars are loaded

// Input Validation (Basic)
if (!process.env.PLIVO_AUTH_ID || !process.env.PLIVO_AUTH_TOKEN || !process.env.PLIVO_PHONE_NUMBER) {
    console.error(""Plivo credentials or phone number missing in .env file."");
    // In a real app, you might want to prevent the app from starting
    // or disable scheduling if Plivo isn't configured.
    // For now, we log the error. The client initialization will likely fail later.
}

// Initialize Plivo client only if credentials exist
let client;
if (process.env.PLIVO_AUTH_ID && process.env.PLIVO_AUTH_TOKEN) {
    client = new plivo.Client(process.env.PLIVO_AUTH_ID, process.env.PLIVO_AUTH_TOKEN);
} else {
    console.warn(""Plivo client not initialized due to missing credentials."");
}

const plivoPhoneNumber = process.env.PLIVO_PHONE_NUMBER;

/**
 * Sends an SMS message using the Plivo API.
 * @param {string} to - The recipient's phone number in E.164 format.
 * @param {string} text - The message content.
 * @returns {Promise<object>} - The Plivo API response.
 * @throws {Error} - If sending fails or Plivo client isn't initialized.
 */
const sendSms = async (to, text) => {
  if (!client) {
    throw new Error(""Plivo client is not initialized. Cannot send SMS."");
  }
  if (!plivoPhoneNumber) {
    throw new Error(""Plivo source phone number (PLIVO_PHONE_NUMBER) is not configured."");
  }
  if (!to || !text) {
    throw new Error(""Recipient phone number (to) and message text are required."");
  }

  console.log(`Attempting to send SMS via Plivo from ${plivoPhoneNumber} to ${to}`);

  try {
    const response = await client.messages.create(
      plivoPhoneNumber, // src
      to,              // dst
      text             // text
      // Optional parameters (e.g., { url: 'status_callback_url' }) can be added here
    );
    // Ensure response structure is handled safely
    const messageUuid = response && response.messageUuid ? response.messageUuid[0] : 'N/A';
    console.log(`Plivo SMS Response: Message UUID ${messageUuid}`);
    // Plivo response includes message_uuid which is useful for tracking
    return response;
  } catch (error) {
    console.error(""Plivo API Error:"", error);
    // Rethrow or handle specific Plivo errors (e.g., invalid number format, insufficient credits)
    throw new Error(`Failed to send SMS via Plivo: ${error.message}`);
  }
};

module.exports = {
  sendSms,
  // Export client if needed elsewhere, but usually better to keep interactions within the service
};

npm install moment-timezone

// services/scheduler.js
const cron = require('node-cron');
const Appointment = require('../models/Appointment');
const { sendSms } = require('./plivoService'); // Use the Plivo service
const moment = require('moment-timezone'); // Use moment-timezone for reliable time zone handling

require('dotenv').config();

const CRON_SCHEDULE = process.env.CRON_SCHEDULE || '* * * * *'; // Default: every minute
const REMINDER_MINUTES_BEFORE = parseInt(process.env.REMINDER_MINUTES_BEFORE || '60', 10);

let task = null; // To hold the cron task instance
let isJobRunning = false; // Simple lock to prevent overlap

/**
 * Checks for appointments needing reminders and sends SMS via Plivo.
 */
const checkAndSendReminders = async () => {
  if (isJobRunning) {
    console.log(`[${new Date().toISOString()}] Reminder check skipped: Previous job still running.`);
    return;
  }
  isJobRunning = true;
  console.log(`[${new Date().toISOString()}] Running reminder check...`);

  // Calculate the time window for reminders
  const now = moment.utc(); // Work with UTC time
  const reminderWindowStart = now.clone(); // Avoid modifying 'now' directly
  const reminderWindowEnd = now.clone().add(REMINDER_MINUTES_BEFORE, 'minutes');

  console.log(`Checking for appointments between ${reminderWindowStart.toISOString()} and ${reminderWindowEnd.toISOString()}`);

  try {
    // Find appointments within the window that haven't had a reminder sent
    const appointmentsToRemind = await Appointment.find({
      appointmentTime: {
        $gte: reminderWindowStart.toDate(), // Greater than or equal to now
        $lte: reminderWindowEnd.toDate()    // Less than or equal to X minutes from now
      },
      reminderSent: false // Only find those not yet reminded
    }).lean(); // Use .lean() for performance if not modifying Mongoose docs directly

    console.log(`Found ${appointmentsToRemind.length} appointments needing reminders.`);

    if (appointmentsToRemind.length === 0) {
      isJobRunning = false; // Release lock
      return; // Nothing to do
    }

    // Process reminders sequentially to avoid overwhelming Plivo API or database
    for (const appointment of appointmentsToRemind) {
      console.log(`Processing reminder for appointment ID: ${appointment._id}`);

      // Format the appointment time for the SMS message *using the stored time zone*
      let localAppointmentTime = 'N/A';
      try {
          localAppointmentTime = moment(appointment.appointmentTime) // This is UTC
                                       .tz(appointment.timeZone) // Convert to user's timezone
                                       .format('h:mm A z'); // e.g., "3:00 PM EDT"
      } catch (tzError) {
          console.error(`Error formatting time for appointment ${appointment._id} with timezone ${appointment.timeZone}:`, tzError);
          // Use UTC time as fallback or skip? For now, log and continue.
          localAppointmentTime = moment(appointment.appointmentTime).utc().format('h:mm A [UTC]');
      }


      const messageText = `Hi ${appointment.name}, this is a reminder for your appointment scheduled at ${localAppointmentTime}.`;

      try {
        // Send SMS using the Plivo service
        await sendSms(appointment.phoneNumber, messageText);
        console.log(`Reminder SMS sent successfully to ${appointment.phoneNumber} for appointment ${appointment._id}`);

        // IMPORTANT: Mark the appointment as reminderSent in the database
        await Appointment.updateOne({ _id: appointment._id }, { $set: { reminderSent: true } });
        console.log(`Marked appointment ${appointment._id} as reminderSent.`);

      } catch (smsError) {
        console.error(`Failed to send reminder or update status for appointment ${appointment._id}:`, smsError);
        // Decide on retry logic:
        // - Log the error and move on (simplest).
        // - Implement a retry count on the appointment document.
        // - Push failed jobs to a separate queue for later processing.
        // For this guide, we'll log and continue.
      }
      // Optional: Add a small delay between sends if hitting rate limits
      // await new Promise(resolve => setTimeout(resolve, 200)); // 200ms delay
    }
  } catch (dbError) {
    console.error('Error querying appointments for reminders:', dbError);
  } finally {
      isJobRunning = false; // Release lock regardless of outcome
      console.log(`[${new Date().toISOString()}] Reminder check finished.`);
  }
};

/**
 * Starts the cron job.
 */
const startScheduler = () => {
  // Validate cron schedule format (basic check)
  if (!cron.validate(CRON_SCHEDULE)) {
      console.error(`Invalid CRON_SCHEDULE format: "${CRON_SCHEDULE}". Scheduler not started.`);
      return;
  }

  console.log(`Scheduler starting with schedule: ${CRON_SCHEDULE}`);

  // Schedule the task
  task = cron.schedule(CRON_SCHEDULE, checkAndSendReminders, {
    scheduled: true,
    // Optional: specify timezone for the cron schedule itself if needed,
    // but the logic inside checkAndSendReminders uses UTC/moment-timezone.
    // timezone: "America/New_York"
  });

  // Optional: You can add listeners for job start/stop if needed
  // task.start(); // Already starts if scheduled: true
  console.log("Reminder scheduler job registered.");
};

/**
 * Stops the cron job gracefully.
 */
const stopScheduler = () => {
  if (task) {
    console.log("Stopping reminder scheduler...");
    task.stop();
    task = null;
    console.log("Scheduler stopped.");
  }
};

// Export functions
module.exports = {
  startScheduler,
  stopScheduler,
  checkAndSendReminders // Export for potential manual triggering or testing
};