Notification System – Workflow Guideline

This document describes how users navigate the UI to use the Notification System, from seeing new notifications to acting on them and managing preferences. It is written from a product workflow perspective and is applicable wherever the Notification System is enabled in Crelio Health.

Demo Video

1. Accessing Notifications

1.1 From the Application

1. Login to Crelio Health with a user that has access to notifications (e.g. lab staff, lab admin, doctor).
2. In the main application, locate the notification icon (bell) in the sidebar or header.
3. Observe the unread badge count on the icon:
   • Shows the number of unread notifications for the current user/session.
   • Updates automatically when new notifications arrive or when items are marked as read.
4. Click the notification icon to open the Notification Center / Inbox.

1.2 Organisation-Level Notifications

Some notifications are organisation-scoped rather than individual:

1. From the lab/organisation login, open the Organisation Notifications or equivalent menu item.
2. This view shows notifications that apply to the entire organisation (e.g. important announcements, organisation report events).

2. Enabling Notifications (Step-by-step)

2.1 Enable browser notifications (client-side)

1. Log in to the application.
2. When prompted by the browser, choose Allow notifications.
3. If you previously blocked notifications:
   • Open the browser site settings (lock icon in the address bar).
   • Set Notifications to Allow.
   • Refresh the page and re-open the app.

2.2 Ensure the user is registered for push (system-side)

Once notifications are allowed:

1. The frontend generates an FCM token for the current browser/device.
2. The token is saved to the backend (token ↔ user/session mapping).
3. The backend subscribes the token to the correct topics (lab/org/role/doctor as applicable).

If any of the above steps fail, the user can still use the in-app Notification Center, but browser push may not be received.

2. Working with the Notification Inbox

Once the Notification Center is open:

1. The system loads the initial list of notifications for the current user and date range.
2. Each row in the grid/list typically shows:
   • Type / Category (e.g. Critical Report, Org Report Ready, Application Message).
   • Title and short message body.
   • Created time.
   • Read status (highlighted for unread).

2.1 Filtering and Searching

Users can refine the list using:

• Status filters
  • Show All, Unread only, or Read notifications.
• Date filters
  • Restrict results to a specific date range.
  • The UI enforces limits (e.g. maximum 6‑month window or row cap) for performance.
• Search
  • Search across title, message body, or other visible fields to quickly find relevant notifications.

2.2 Pagination and Load More

• The list is paginated to keep responses fast.
• A Load more or pagination control lets users load older notifications when needed.

3. Setting User Notification Preferences (Step-by-step)

Where enabled, users can control which notifications they receive.

1. Open User / Profile Settings.
2. Navigate to Notification Settings.
3. Configure:
   • Enable/Disable notifications (master toggle).
   • Notification types (e.g. Critical Report, Org Report Ready, Application Message).
   • Channels:
     • Browser push
     • In-app
     • Both (if supported)
4. Click Save.
5. Validate by triggering a test notification (or wait for the next real event) and confirm:
   • Badge count updates.
   • Inbox receives the item.
   • Browser push appears if enabled.

3. Acting on Notifications

3.1 Opening a Notification

1. Click on a notification row.
2. The system:
   • Marks the notification as read (if it was previously unread).
   • Updates the unread badge count accordingly.
   • Navigates to or opens the relevant screen, for example:
     • Report Review Modal for Org Report Ready / Critical Report alerts.
     • A dedicated page for organisation announcements or configuration changes.

3.2 Common Actions

Depending on implementation, users may be able to:

• Mark as read/unread from the list (per row or in bulk).
• Open details to see the full message and context.
• Dismiss or close banners/toasts while still retaining the item in the inbox.

4. Sending Notifications (How it happens)

Notifications are typically sent by the backend when business events occur.

1. A business event occurs (e.g. critical report finalised, organisation report ready, delay detected, system announcement created).
2. Backend resolves:
   • Notification type and template/message parameters.
   • Recipients (users/roles) and topics (lab/org/doctor).
3. Backend creates a notification record and recipient activity entries.
4. Backend triggers delivery:
   • FCM for browser/mobile push (topic/device-token based).
   • In-app visibility via the Notification APIs consumed by the UI.

For exact endpoints used by clients and delivery flows, see the Notification System Backend → API Reference docs.

5. Receiving Notifications (What the user sees)

When a notification is generated:

1. Browser push notification (if enabled)
   • Appears even if the app tab is not focused (or the app is closed), depending on browser rules.
2. In-app banner/toast (if implemented)
   • Appears inside the app while the user is active.
3. Inbox badge update
   • Unread count increments.
4. Inbox entry
   • A new row appears in the Notification Center list.

6. Typical Use Cases

4.1 Critical Report Notifications

1. A critical report is finalised or passes a configured threshold.
2. Backend triggers a Critical Report notification.
3. User sees:
   • A browser push (if enabled).
   • An in‑app banner.
   • An incremented unread badge in the Notification icon.
4. User clicks the notification:
   • The critical review screen/modal opens.
   • The notification is marked as read.

4.2 Organisation Report Ready

1. An organisation report (e.g. summary or periodic report) becomes ready.
2. A corresponding Org Report Ready notification is created.
3. When the user clicks it:
   • The system opens the Org Report Review view or modal.
   • Users can take configured actions (review, acknowledge, etc.).

7. Lab / Organisation-Level Settings

Lab admins may configure behaviour for the entire organisation:

1. Open Organisation / Lab Settings.
2. Go to the Notification Settings or equivalent module.
3. For each notification type, admins can:
   • Enable or disable it for the lab.
   • Optionally edit message templates (subject/body placeholders).
4. Review notification history / activity logs to:
   • Confirm that notifications are being generated and delivered.
   • See which users received or read specific messages.

8. Environment and Rollout Considerations

• UAT environments
  • Often configured with test topics and non‑production Firebase projects.
  • Used to validate end‑to‑end flows (inbox, badges, review modals) before release.
• Production environments
  • Use real lab and organisation topics.
  • Follow rollout steps from the deployment plan and roadmap (see the Notifications items in the 2026 Roadmap sheet).

9. Related References

• Design & Scope: Notifications (MVP) Whimsical
• Epic: EN-11322 – Notification System
• Roadmap & Tasks: Roadmap 2026 – B2B & Finance