Notification service

Data structures

The core responsibility of the notification service is handling all operations related to in-app notifications.
Next to creating, listing, marking as read, and deleting notifications, this service persists a normalized notification entity and separate recipient rows per user to track delivery status. Notifications are lightweight abstractions: they do not contain heavy payloads or media. Instead, they store metadata (title, message, link, source) and reference other services via navigational links.

Notifications can be targeted directly to users or broadcasted to all members of a course. User preferences (per-category toggles) are respected during delivery. If the user settings cannot be retrieved, the service defaults to delivering the notification to avoid missed critical information.

A more technical description of the notification service and its GraphQL endpoints can be found in our Github Repository README.

Notification types

Currently, our system supports notifications originating from multiple domains (via the shared event model):

  1. Media notifications (e.g., new material published) from the media service.

  2. Content notifications (e.g., chapter updates) from the content service.

  3. Course-related notifications (e.g., course material) from the course service.

  4. Other platform notifications (e.g., assignments, gamification) as needed.

Beyond the source category and optional course context, the notification service does not store the full domain object. Detailed content remains in the corresponding services and is accessed via the link stored with each notification.

Tracking of delivery and read status

For each targeted user, the service stores a recipient row with a status: UNREAD, READ, or DO_NOT_NOTIFY (the latter when user preferences mute a category). Clients can query:

  • The list of notifications for a user, with the mapped read flag.

  • The unread count for a user.

  • Mutations to mark a single notification as read or mark all as read.

  • Mutations to delete a single notification or delete all notifications.

Ingestion of new notifications happens via domain events emitted by underlying services such as the media service, quiz service, flashcard service, content service, etc. The notification service consumes these events, persists the notification, materializes recipient rows, and (if applicable) pushes live updates to subscribers. When a notification becomes orphaned (no remaining recipients), it is removed to keep storage lean.

Notification subscriptions

In addition to list queries, the notification service provides a live subscription for clients to receive newly created notifications in real time. Subscriptions can be filtered by the authenticated user. Optional filters (such as source category or course) can be layered by the API gateway if required.

A typical subscription flow:

  • Clients subscribe to the “notification added” stream for a specific user.

  • When an event is ingested and the user is an eligible recipient (and not muted), a NotificationData payload is emitted.

  • The payload contains: id, title, description, link, createdAt, and a read flag (initially false).

Management of preferences and recipients

Per-user notification preferences (category toggles) are managed by the user/settings domain and queried by the notification service during delivery. If settings are not available at delivery time, the service defaults to delivering the notification to prevent lost information.

Recipient materialization and cleanup:

  • For direct notifications, the event names explicit user IDs.

  • For course-wide notifications, the service resolves course membership via the course service and materializes a recipient row for each member.

  • When a user deletes a notification, only their recipient row is removed; if no recipient rows remain, the notification entity is also deleted.

  • If a user or course is removed by upstream services, corresponding recipient rows are cleaned up as part of standard data hygiene (either via events or periodic maintenance), ensuring referential integrity.

For more information on how other services emit domain events and how users can tune preferences, we recommend reading the corresponding service documentation