feat(notifications): implement real-time notification system

[mijinummi]

[FEAT] Real-Time Notification System

Summary

Closes #411
Implements a complete real-time notification infrastructure for the quest service, providing instant WebSocket delivery, durable notification history, user preference controls, queued processing, delivery tracking, retries, and notification aggregation.

The system is designed to reliably deliver notifications without overwhelming users or the backend, while maintaining an auditable record of notification delivery and failure states.

What Changed

🔔 Notification Architecture

Introduced a centralized notification architecture covering the complete notification lifecycle:

Application Event
      ↓
Notification Service
      ↓
Notification Queue
      ↓
Delivery Worker
      ↓
WebSocket Gateway
      ↓
Connected User

Notifications are persisted and processed asynchronously, separating event generation from real-time delivery.

⚡ WebSocket Delivery

• Added WebSocket-based real-time notification delivery.
• Connected users receive notifications immediately without polling.
• Notifications are routed to the appropriate authenticated user.
• Connection/disconnection handling is integrated into the delivery flow.

🏷️ Notification Types

Added structured notification types to provide consistent notification payloads across the backend.

Notification metadata can be used to distinguish events and provide clients with the information required to render the appropriate notification experience.

⚙️ User Preferences

Implemented user notification preferences so users can control which notification categories they receive.

Preference checks occur before delivery, ensuring disabled notification types are not unnecessarily pushed to users.

Notification Event
       ↓
Check User Preferences
       ↓
Enabled?
   ┌───┴───┐
  Yes      No
   ↓        ↓
Queue     Skip
   ↓
Deliver

📬 Notification Queue

Introduced queued notification processing to prevent large notification bursts from overwhelming the WebSocket layer or application workers.

The queue provides:

• Asynchronous processing
• Controlled delivery
• Retry support
• Failure isolation
• Improved scalability during notification spikes

📍 Delivery Tracking

Added delivery status tracking throughout the notification lifecycle.

The system can distinguish between states such as:

• Pending
• Processing
• Delivered
• Failed
• Retrying

This provides an auditable delivery trail and makes failed notifications easier to diagnose.

🔁 Retry Logic

Added retry handling for transient delivery failures.

Failed notifications are reprocessed according to the configured retry policy rather than being permanently lost after the first unsuccessful attempt.

Delivery Attempt
      ↓
Success?
  ┌───┴───┐
 Yes      No
  ↓        ↓
Delivered Retry
           ↓
      Retry Limit?
       ┌───┴───┐
      No       Yes
       ↓        ↓
    Requeue   Failed

🗂️ Notification History

Implemented persistent notification history so users and application services can access previously generated notifications.

History provides visibility into notifications that were delivered, failed, or otherwise processed by the system.

📦 Notification Aggregation

Added aggregation for compatible notification events to prevent users from being flooded by repetitive notifications during high-volume activity.

Related events can be grouped into a single notification representation where appropriate.

This improves the user experience while reducing unnecessary delivery traffic.

Reliability & Scalability

The notification pipeline separates notification creation from delivery:

Event
 ↓
Persist Notification
 ↓
Queue
 ↓
Worker
 ↓
Preference Check
 ↓
WebSocket Delivery
 ↓
Track Result
 ↓
Retry / Complete

This allows the system to continue operating reliably when users are temporarily disconnected or when notification volume increases significantly.

Testing

Added comprehensive coverage for:

• Notification creation.
• Notification type handling.
• WebSocket connection and delivery.
• User preference enforcement.
• Queue processing.
• Delivery tracking.
• Failed delivery handling.
• Retry behaviour.
• Notification history.
• Notification aggregation.
• Connected and disconnected users.
• End-to-end notification delivery.

Acceptance Criteria

• Notifications are delivered in real time through WebSockets.
• User notification preferences are respected.
• Notification processing is queue-based to prevent overwhelming the system.
• Notification history is persisted and accessible.
• Failed deliveries are retried according to the configured retry policy.
• Delivery status is tracked throughout the notification lifecycle.
• Notification types are structured and consistently handled.
• Related notifications can be aggregated where appropriate.
• Comprehensive tests cover the notification lifecycle.
• Existing application behaviour remains unaffected.

Result

The quest service now provides a reliable, scalable real-time notification system with WebSocket delivery, preference management, queued processing, retry handling, delivery tracking, persistent history, and aggregation.

This provides users with immediate notifications while ensuring the backend can safely handle transient failures and high-volume notification workloads.

[drips-wave]

@mijinummi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits