Skip to content

NOTIFICATION_SYSTEM.md

Latest commit

 

History

History
246 lines (200 loc) · 8.24 KB

NOTIFICATION_SYSTEM.md

File metadata and controls

246 lines (200 loc) · 8.24 KB
Raw

Event Notification System

Overview

The notification system automatically alerts users when:

  1. New events are added to the platform
  2. Event reminders for registered events (1 day and 1 hour before)

This feature works for students, staff, events office, TAs, and professors.

How It Works

Backend Implementation

  1. Notification Models

    • SystemNotification: Stores all system-wide notifications
    • Located: server/models/SystemNotification.js

  2. Notification Controller

    • Handles fetching, reading, and deleting notifications
    • Located: server/controllers/notificationController.js
    • Endpoints:
      • GET /api/notifications - Get user's notifications
      • PUT /api/notifications/:id/read - Mark as read
      • PUT /api/notifications/read-all - Mark all as read
      • DELETE /api/notifications/:id - Delete notification

  3. Notification Service

    • notifyNewEvent() - Creates notifications for all eligible users
    • Located: server/utils/notificationService.js
    • Called when:
      • Workshop is published (by Events Office)
      • Trip is created (by Events Office)
      • Conference is created (by Events Office)
      • Bazaar is created (by Events Office)

  4. Event Controllers

    • Workshop: publishWorkshop() triggers notifications
    • Trip: createTrip() triggers notifications
    • Conference: createConference() triggers notifications
    • Bazaar: createBazaar() triggers notifications

Frontend Implementation

  1. Notification Service

    • Located: client/src/services/notificationService.js
    • Provides API calls for notification operations

  2. NotificationCenter Component

    • Located: client/src/components/common/NotificationCenter.jsx
    • Features:
      • Bell icon with unread count badge
      • Dropdown with notification list
      • Auto-refresh every 30 seconds
      • Mark as read on click
      • Delete individual notifications
      • Mark all as read button

  3. Integration

    • Added to ProfileHeader component
    • Only visible to: student, staff, ta, professor, events_office

User Experience

For Students/Staff/TA/Professor

  1. When a new event is published, a notification appears
  2. Bell icon shows red badge with unread count
  3. Click bell to view notifications
  4. Click notification to mark as read
  5. Notifications auto-refresh every 30 seconds

For Events Office

  1. Receive notifications when creating events
  2. Can manage their own notifications
  3. See which events they've published

Notification Types

  • new_event - New event added (workshop, trip, conference, bazaar)
  • event_reminder_1day - Event reminder 1 day before (for registered events)
  • event_reminder_1hour - Event reminder 1 hour before (for registered events)
  • registration_confirmed - Registration successful
  • payment_received - Payment processed
  • refund_processed - Refund issued

Event Reminder System

How Reminders Work

  1. Automatic Scheduler

    • Runs every 5 minutes on the server
    • Checks all active registrations
    • Creates reminder notifications at the right time

  2. 1-Day Reminder

    • Sent 24 hours before event start time
    • Detection window: 23-25 hours before event
    • Only sent once per registration

  3. 1-Hour Reminder

    • Sent 1 hour before event start time
    • Detection window: 55-65 minutes before event
    • Only sent once per registration

  4. Smart Deduplication

    • System checks if reminder already exists
    • Prevents duplicate reminders for same event
    • Uses unique combination: user + event + registration

Eligible Users for Reminders

  • Students
  • Staff
  • TAs
  • Professors
  • Events Office members

Requirement: User must be registered for the event

Reminder Message Format

1-Day Reminder:

Title: Event Reminder: [Event Name]
Message: The event "[Event Name]" starts in 1 day! Don't forget to attend.

1-Hour Reminder:

Title: Event Reminder: [Event Name]
Message: The event "[Event Name]" starts in 1 hour! Get ready.

Testing the Feature

Test 1: New Event Notifications

  1. Login as Events Office
  2. Publish a Workshop or Create a Trip/Conference/Bazaar
  3. Login as a Student/Staff/TA/Professor
  4. Check the notification bell in the header
  5. Click the bell to see the new event notification

Test 2: Event Reminder Notifications (1 Day)

  1. Create an event with start date exactly 24 hours from now
  2. Register for the event as a student/staff/TA/professor
  3. Wait for the scheduler to run (runs every 5 minutes)
  4. Check notifications - you should see a 1-day reminder

Test 3: Event Reminder Notifications (1 Hour)

  1. Create an event with start date exactly 1 hour from now
  2. Register for the event as a student/staff/TA/professor
  3. Wait for the scheduler to run (runs every 5 minutes)
  4. Check notifications - you should see a 1-hour reminder

Quick Test Script

To test reminders immediately, you can create events with these times:

  • For 1-day reminder: Set event start to new Date(Date.now() + 24 * 60 * 60 * 1000)
  • For 1-hour reminder: Set event start to new Date(Date.now() + 60 * 60 * 1000)

Technical Details

Notification Creation Flow - New Events

1. Event Office publishes/creates event
2. Event controller calls notifyNewEvent()
3. Service queries all active users with eligible roles
4. Creates SystemNotification documents for each user
5. Frontend polls for notifications every 30s
6. Users see bell icon with badge

Notification Creation Flow - Reminders

1. Scheduler runs every 5 minutes (server.js)
2. checkAndCreateReminders() function executes
3. Queries all active registrations (status: 'registered')
4. For each registration:
   a. Fetches the event details
   b. Calculates time until event
   c. Checks if within 1-day window (23-25 hours)
   d. Checks if within 1-hour window (55-65 minutes)
   e. Verifies no duplicate reminder exists
   f. Creates SystemNotification for the user
5. Logs reminder creation to console
6. Frontend auto-refreshes and shows new notifications

Scheduler Configuration

  • Location: server/server.js line 58-72
  • Interval: 5 minutes (300,000 ms)
  • Initial Run: On server startup
  • Error Handling: Wrapped in try-catch, logs errors without crashing

Reminder Detection Windows

  • 1-Day Window: 23-25 hours before event (2-hour tolerance)
  • 1-Hour Window: 55-65 minutes before event (15-minute tolerance)
  • Why windows?: Ensures scheduler catches reminders even if it runs slightly off-time

Permissions

  • All roles (student, staff, ta, professor, events_office) can:
    • View their own notifications
    • Mark notifications as read
    • Delete their own notifications
    • Mark all as read

Performance

  • Notifications are indexed by user and read status
  • Polling interval: 30 seconds (configurable)
  • Batch creation for efficiency
  • Limit: 100 most recent notifications per user
  • Reminder scheduler: 5-minute intervals
  • Deduplication prevents duplicate reminders
  • Query optimization with indexed fields

Important Notes

Reminder Prerequisites

  1. ✅ User must be registered for the event
  2. ✅ Registration status must be 'registered' (not 'cancelled')
  3. ✅ Event must have a valid start date/time
  4. ✅ Server must be running (scheduler needs to be active)

Event Types Supporting Reminders

  • ✅ Workshops - Uses startAt field
  • ✅ Trips - Uses startDate field
  • ✅ Conferences - Uses startDate field
  • ✅ Bazaars - Uses startDate field

Troubleshooting

Reminders not appearing?

  1. Check if server is running (node server.js)
  2. Verify registration exists in database
  3. Check server console for "Created X-day/hour reminder" logs
  4. Ensure event time is exactly 24 hours or 1 hour away
  5. Check notification bell icon for unread count
  6. Wait up to 5 minutes for scheduler to run

Console Logs to Monitor

  • Reminder scheduler started (checking every 5 minutes)
  • Created 1-day reminder for [userId] - [eventName]
  • Created 1-hour reminder for [userId] - [eventName]

Future Enhancements

  • Real-time notifications using WebSockets
  • Push notifications for mobile
  • Email notifications for important events
  • Notification preferences/settings
  • Notification categories and filters