Event Scheduler API

A robust backend API for scheduling events, managing invitees across time zones, and sending automated email reminders. Built with Node.js, Express, and MongoDB, this production-grade API supports authentication, event creation, calendar integration, and cron-based notifications.

---

API Documentation

• You can explore and test all the API endpoints in two ways:
  • Open the Swagger UI in your browser for an interactive experience.
  • Or check out the full collection on Postman here: View Postman Docs

---

Table of Contents

• Project Overview
• Core Features
• Tech Stack
• Folder Structure
• API Endpoints
• Authentication
• Reminder Job (Cron)
• Environment Variables
• Getting Started
• Future Improvements

---

Project Overview

This API allows authenticated users to create and manage events, invite participants based on their cities, and automatically send reminder emails before the event starts. Timezone handling is deeply integrated to ensure accuracy in scheduling and notifications. Additionally, invitees receive .ics calendar files compatible with Google and Outlook calendars.

---

Core Features

User Management

• Secure registration and login via JWT
• Passwords hashed using bcryptjs

Event Management

• Create, update, delete events with title, description, location, duration
• Events are scheduled using ISO date-time standards

Invitee Management

• Add invitees by email and city
• Automatically detect invitee timezones
• Resend invitations
• Delete invitees from an event

Smart Timezone Handling

• Uses city-timezones and dayjs to localize event times for invitees
• Emails show event time in the invitee's local timezone

Calendar (.ics) Integration

• Automatically sends .ics files for calendar scheduling via email

Email Notifications

• On invite, update, and reminders
• Uses nodemailer under the hood

Automated Reminder System

• A cron job runs every minute to check for upcoming events
• Reminders are sent X minutes (default: 45) before event start
• Respects timezones of each invitee

---

Tech Stack

• Backend: Node.js, Express.js
• Database: MongoDB with Mongoose
• Authentication: JWT
• Timezone Management: Day.js + city-timezones
• Email: Nodemailer
• Scheduling: node-cron
• Calendar Files: ical-generator

---

Folder Structure

project-root/
│
├── config/              # DB connection
├── controllers/         # Business logic for auth, events, invites
├── cron/                # Scheduled jobs (reminders)
├── middlewares/         # Auth, error handler
├── models/              # Mongoose schemas
├── routes/              # API endpoints
├── services/            # Email service & ics file generation
├── utils/               # Helper functions (e.g., timezone resolver)
├── .env                 # Environment configuration
├── server.js            # Entry point
└── package.json

---

API Endpoints

Auth Routes (/api/auth)

• POST /register – Create a new user
• POST /login – Authenticate and return JWT

Event Routes (/api/events)

• POST / – Create an event (auth required)
• GET /me – Get all events created by the user
• GET /:id – Get details of a single event
• PUT /:id – Update an event
• DELETE /:id – Delete an event

Invitee Routes (/api/invites)

• POST /:eventId – Add invitee(s) to event
• GET /:eventId – List all invitees for event
• POST :eventId//resend/:inviteeId – Resend invite to an invitee
• DELETE /:eventId/remove/:inviteeId – Remove an invitee from event

---

Authentication

All /api/events and /api/invites routes require a valid JWT in the Authorization header.

Authorization: Bearer <token>

---

Reminder Job (Cron)

• File: cron/reminderJob.js

• Interval: Every minute

• Logic:

  • Finds all events starting within the next X minutes (default: 45)
  • Sends reminder emails to each invitee with event details localized to their timezone
  • Includes .ics calendar attachment for seamless scheduling

---

Environment Variables

Create a .env file in the root with the following keys:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret
EMAIL_HOST=smtp_provider_host
EMAIL_PORT=587
EMAIL_USER=your_email
EMAIL_PASS=your_email_password
REMINDER_TIME_MINUTES=45

---

Getting Started

1. Clone the repository

git clone https://github.com/your-repo/event-scheduler-api.git
cd event-scheduler-api

2. Install dependencies

npm install

3. Setup .env

Create a .env file with the variables mentioned above.

4. Start the server

npm start

5. Health Check

Visit http://localhost:5000/healthz to verify server is up.

---

Future Improvements

• RSVP system (Accept / Maybe / Decline)
• Invitee status tracking
• Swagger API documentation
• Retry queue for failed email deliveries (e.g., using BullMQ + Redis)
• Google Calendar or Outlook syncing
• Role-based permissions (admin vs team members)
• Frontend dashboard (React) for event/invitee management

---

License

This project is licensed under the MIT License.