directus-task-management/NOTIFICATION_SYSTEM.md

Real-time Notification System

Overview

The notification system provides real-time and email notifications for task management events using Socket.io and Nodemailer.

Features

Real-time Notifications (Socket.io)

• Instant push notifications to connected clients
• User-specific notification channels
• Support for multiple device connections per user
• Notification acknowledgment and read status tracking

Email Notifications (Nodemailer)

• Configurable email delivery (instant, hourly, daily, weekly digests)
• HTML email templates with priority indicators
• Email queuing with retry mechanism using Bull queue
• SMTP configuration support

Notification Types

• TASK_ASSIGNED - When a task is assigned to a user
• TASK_UPDATED - When task details are modified
• TASK_COMPLETED - When a task is marked as done
• TASK_OVERDUE - When a task passes its due date
• COMMENT_ADDED - When someone comments on a task
• MENTION - When a user is mentioned
• STATUS_CHANGED - When task status changes
• DEADLINE_APPROACHING - Reminder for upcoming deadlines
• WORKFLOW_TRIGGERED - When workflow events occur
• COLLABORATION_INVITE - When invited to collaborate

Priority Levels

• URGENT - Red indicator, immediate attention required
• HIGH - Yellow indicator, high priority
• MEDIUM - Blue indicator, normal priority
• LOW - Gray indicator, low priority

Configuration

Environment Variables

# Socket.io Configuration
PORT=3000
CORS_ORIGIN=http://localhost:3000

# Email Configuration (Optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@taskmanagement.com

# Redis Configuration (for email queue)
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT Configuration
JWT_SECRET=your-secret-key

# Directus Configuration
DIRECTUS_URL=http://localhost:8055
DIRECTUS_EMAIL=admin@example.com
DIRECTUS_PASSWORD=admin-password

API Endpoints

REST API

Get Notifications

GET /api/notifications
Query params: page, limit, unreadOnly

Mark as Read

PUT /api/notifications/:notificationId/read

Mark All as Read

PUT /api/notifications/read-all

Get Preferences

GET /api/notifications/preferences

Update Preferences

PUT /api/notifications/preferences
Body: { email: {...}, realtime: {...}, doNotDisturb: {...} }

Subscribe to Types

POST /api/notifications/subscribe
Body: { types: ['task_assigned', 'mention'] }

Unsubscribe from Types

POST /api/notifications/unsubscribe
Body: { types: ['task_overdue'] }

Socket.io Events

Client → Server Events

• notification:markRead - Mark single notification as read
• notification:markAllRead - Mark all notifications as read
• notification:updatePreferences - Update user preferences
• notification:subscribe - Subscribe to notification types
• notification:unsubscribe - Unsubscribe from notification types

Server → Client Events

• notification:new - New notification received
• notification:read - Notification marked as read
• notifications:allRead - All notifications marked as read
• notifications:pending - Batch of pending notifications
• preferences:updated - Preferences updated successfully

Testing

1. Start the Server

npm run dev

2. Open Test Client

Open src/notifications/test-client.html in a browser

3. Generate JWT Token

// Generate test JWT token
const jwt = require('jsonwebtoken');
const token = jwt.sign(
  { userId: 'test-user-id' },
  'your-secret-key',
  { expiresIn: '1h' }
);
console.log(token);

4. Connect and Test

1. Enter the JWT token in the test client
2. Click "Connect"
3. Send test notifications
4. Verify real-time delivery

5. Test with Node.js Client

node test-notification.js

Integration with Task System

The notification system automatically sends notifications when:

1. Task Assignment: Users receive notifications when assigned to tasks
2. Status Changes: Notifications on task status transitions
3. Due Date Alerts: Automatic reminders for approaching deadlines
4. Comments: Notifications when comments are added to tasks
5. Mentions: Direct notifications when mentioned in tasks/comments

Example Integration

// In task assignment service
await notificationService.sendNotification(assigneeId, {
  type: NotificationType.TASK_ASSIGNED,
  priority: NotificationPriority.HIGH,
  title: 'New Task Assigned',
  message: `You have been assigned to: ${task.title}`,
  actionUrl: `/tasks/${taskId}`,
  actions: [{
    label: 'View Task',
    action: 'view_task',
    url: `/tasks/${taskId}`
  }]
});

User Preferences

Users can configure:

Email Preferences

• Enable/disable email notifications
• Set delivery frequency (instant, hourly, daily, weekly)
• Select notification types to receive via email

Real-time Preferences

• Enable/disable real-time notifications
• Select notification types for real-time delivery
• Enable/disable sound alerts
• Enable/disable desktop notifications

Do Not Disturb

• Enable DND mode
• Set DND schedule (start/end times)
• Configure timezone for DND

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│   Socket.io  │────▶│  Notification│
│   (Browser) │     │    Server    │     │   Service   │
└─────────────┘     └──────────────┘     └─────────────┘
                            │                     │
                            ▼                     ▼
                    ┌──────────────┐     ┌─────────────┐
                    │   Express    │     │   Email     │
                    │   REST API   │     │   Queue     │
                    └──────────────┘     └─────────────┘
                            │                     │
                            ▼                     ▼
                    ┌──────────────┐     ┌─────────────┐
                    │   Directus   │     │   SMTP      │
                    │   Database   │     │   Server    │
                    └──────────────┘     └─────────────┘

Troubleshooting

Socket.io Connection Issues

• Verify JWT token is valid
• Check CORS configuration
• Ensure server is running on correct port
• Check firewall/proxy settings

Email Delivery Issues

• Verify SMTP credentials
• Check spam folder
• Ensure Redis is running for queue
• Review email queue logs

Notification Not Received

• Check user preferences
• Verify user is not in DND mode
• Check notification type subscriptions
• Review server logs for errors

Future Enhancements

• Push notifications (FCM/APNs)
• SMS notifications (Twilio)
• Slack/Teams integration
• Custom notification templates
• Notification scheduling
• Advanced filtering and search
• Notification analytics
• Bulk notification management