Skip to Content

Notifications

  • Code: ACC-NTF
  • Module: Account
  • Type: System Record

1. Overview

Notifications tell users about relevant events, such as a PO that needs to be submitted or data that has changed. Notifications arrive through three channels: an inbox with the latest list and a searchable history, toasts that appear instantly while the app is open and connected, and device notifications that still appear when the app is closed if the user turns them on. Every notification points to the related data, so users can open it with a single click.

Expected outcome: users do not miss work that is waiting for them, and can go straight to the related data.

2. Problem

Without automatic notifications, users have to open each module one by one to know that a task or change is waiting. As a result:

  • A task waiting for someone, such as a PO the PIC must submit, is not known without opening every module.
  • Users who are not currently using the app miss important events.
  • Notifications without a link force users to look up the data manually.

3. Goals & Non-goals

3.1 Goals

  • Users know there is work waiting without opening each module one by one.
  • Important events still arrive even when the user is not using the app.
  • A notification can be followed up directly at the related data.
  • Users can choose whether to receive device notifications, while toasts are automatic as long as the app is connected.

3.2 Non-goals

  • Notification settings per type of event.
  • Notifications by email or WhatsApp.
  • Deleting notifications that have been received.
  • Creating notifications manually from inside the app.

4. Business Rules

Business rules are the set of provisions and constraints that apply to Notifications across the whole application, on every screen and action involved, whoever performs them. These rules are the single source of truth: if another part of this PRD seems to differ, the rule here applies.

  • BR-01 Users only receive and see their own notifications. Inactive accounts, or accounts whose email is not verified, follow the restrictions in Authentication.
  • BR-02 Every notification has a title, content, and an optional destination link: a ready-made address of a page inside the app. The app simply redirects the user to that link when the notification is opened, without a mapping list of its own. The destination page is decided and written in the PRD of the feature that triggers the notification (its Notifications section). The View Details button is only available if the notification has a link. 🚧 Not yet: FE + BE
  • BR-03 A notification is always stored in the inbox, and is still shown on the device even if its content is incomplete. Opening a notification from the inbox or a toast marks it as read, while opening it from a device notification does not.
  • BR-04 There are three channels. The inbox is always on. In-app notifications (toasts) have no setting: they are on automatically if the app connects to the realtime connection when it loads, and off if it fails. Device notifications are on if the user turns on the Notifications toggle and allows them; this setting is stored per device, not per account. 🚧 Not yet: FE
  • BR-05 Device notification permission is only requested when the user turns on the Notifications toggle themselves, never automatically.
  • BR-06 One user can have device notifications on many devices. A device’s notifications are removed when the user logs out, the device is revoked or its login expires, the password is reset or changed, or a changed login email is verified.
  • BR-07 As long as browser notification permission is still granted, the app registers device notifications again every time it is opened, so users do not need to turn them back on after they were removed (BR-06).
  • BR-08 Every time the app loads or reloads, it tries to connect to the realtime connection. If it succeeds, toasts are on; if it fails, toasts are off without any notice to the user, and the inbox and device notifications keep working. 🚧 Not yet: FE

5. Flow

5.1 Main Flowchart

  1. Notification Created — An event relevant to the user, such as a PO that needs to be submitted, creates one notification addressed to them (BR-01).
  2. Stored in Inbox — A notification is always stored in the inbox, so it can still be read even if the other channels are off (BR-03).
  3. Toast Appears — If the app has connected to the realtime connection and the user has the app open, the notification appears instantly as a toast without reloading the page (BR-04, BR-08). 🚧 Not yet: FE
  4. Device Notification Appears — If the Notifications toggle is on, the notification appears on the device even when the app is closed (BR-04).
  5. Choose How to Open — The user opens the notification through the bell or the Notifications page, or directly from a toast or device notification.
  6. Read Notification Details — The user reads the title, time, and content of the notification in a dialog. The View Details button takes the user to the destination page (BR-02, BR-03).
  7. Destination Page — The user lands directly on the related data without looking for it (BR-02).
  8. Set Notifications — From the settings in the header, the user turns the Notifications toggle on or off for this device. Toasts have no setting (BR-04). 🚧 Not yet: FE
  9. Allow or Revoke Permission — The user turns notifications on by granting browser permission, or turns them off to remove notifications on this device (BR-05, BR-06).

5.2 Status Lifecycle

StatusDescriptionNext
UnreadThe notification has not been opened and is highlighted in the listRead
ReadThe notification has been opened and is no longer counted as unread—

5.3 Channel Delivery

Additional information for the Frontend and Backend teams. The same notification is sent to all channels at once; the table below shows how the two channels besides the inbox differ:

App Toast NotificationBrowser Push Notification
WebSocketYesNo
How it worksThe browser opens a WebSocket connection that stays alive while the app is open. The server pushes the notification through it and the toast appears instantly.The server sends to the browser’s own push service (Chrome, Firefox, Safari, each has its own). That service forwards it to the device, so it arrives even when the app is closed.
Backend technology (retail-api)Laravel Reverb (WebSocket server), Laravel broadcast channel, private channel tenant.users.{userId}laravel-notification-channels/webpush, Web Push protocol with VAPID keys, subscriptions stored in the push_subscriptions table
Frontend technology (retail-app)laravel-echo + pusher-js (Reverb uses the Pusher protocol), toast via sonnerService Worker (public/sw.js), Push API (PushManager), and Notification API for permission
User settingNo toggle; on automatically if the WebSocket connection succeeds when the app loads (BR-04, BR-08)Notifications toggle; on when the user grants browser permission (BR-04, BR-05) 🚧 Not yet: FE
AuthorizationEndpoint /api/broadcasting/authSubscriptions are registered through /api/auth/notifications/subscriptions
If not deliveredThe toast does not appear while the connection is down; the notification stays in the inboxThe push service discards it if the device is unreachable for more than 1 hour; it stays in the inbox

The inbox uses neither: notifications are stored in the database and read through a regular API, so they are always available (BR-03).

6. Document Structure

6.1 General

FieldTypeRequiredDefaultRules
TitleText—Built from the eventFirst line of the notification
ContentText—Built from the eventDescription of the notification
Created AtDate & Time—When the notification is createdShown relatively, for example “5 minutes ago”
Read AtDate & Time—EmptyFilled when the notification is opened (BR-03)
DestinationText—Determined from the eventAddress of a page inside the app, for example /account/linked-devices; empty if there is no related page (BR-02) 🚧 Not yet: FE + BE

6.2 Device Notification

FieldTypeRequiredDefaultRules
DeviceRef. Device—Taken from the login when device notifications are turned onTies the notification to a Linked Device (BR-06)
Subscription DataTextYesGiven by the browser when allowedTechnical data from the browser used to deliver notifications; not shown to the user

7. UI Structure

This section defines how Notifications is displayed and operated: the bell, the page, the detail dialog, and notification settings. It only governs presentation and interaction; the rules for content and values still follow Document Structure.

7.1 Bell

PartExample ValueComponent
Count Badge12, or 99+Badge
TabAll, UnreadTabs
List10 latest notificationsList Item, with module icon, title, and relative time
View All Link—Link to the Notifications page

Actions: View All.

7.2 Notifications Page

FieldControlBehavior
TabAll/Unread toggle (in the header, as icons)Kept when the page reloads
SearchText InputKept when the page reloads; searches the title and content
ListList Item, loaded in batchesLoad More button

Actions: Mark All as Read, on the same row as the search.

7.3 Detail Dialog

FieldComponent
TitleText
ContentText 🚧 Not yet: FE
TimeText, relative
View Details ActionButton, only shown if the notification has a destination link (BR-02)

Actions: View Details, Close.

7.4 Notification Settings

Available in the header settings.

FieldControlBehavior
NotificationsToggleControls device (push) notifications on this device; reflects whether this device has device notifications; disabled with a note if unsupported or permission is denied (BR-04, BR-05) 🚧 Not yet: FE

Actions: turn the toggle on or off. Toasts have no toggle (BR-04).

8. User Stories

US-01 - Notification bell

As a user, I want to see the latest notifications from the header, so I quickly know when something new arrives.

IDAcceptance criteria
AC-01.1The bell shows an unread count badge; more than 99 is shown as “99+”.
AC-01.2The popover shows the 10 latest notifications with All and Unread tabs.
AC-01.3The View All link opens the Notifications page; clicking an item closes the popover and opens the detail dialog.
AC-01.4Empty states: “No notifications yet” or “No unread notifications”.
AC-01.5A notification appears when an event is addressed to the user (BR-01). Needs confirmation: no business module sends notifications yet; the only sender is a test notification that exists only in non-production environments.

US-02 - Notifications page

As a user, I want to see all my notifications, so I can find older ones.

IDAcceptance criteria
AC-02.1The All and Unread tabs and the search keyword are kept when the page reloads; search matches the title and content.
AC-02.2The list loads in batches of 15 with a Load More button.
AC-02.3The Mark All as Read button marks all the user’s notifications as read and updates the list and badge (BR-03).
AC-02.4Unread notifications are visually distinct, and the icon follows the module (inventory, purchase, settings, or a bell if unrecognized).

US-03 - Details and navigation

As a user, I want to read the full notification and open the related data.

IDAcceptance criteria
AC-03.1Clicking an item marks it as read if it is not yet, then opens a detail dialog with the title, relative time, and content (BR-03).
AC-03.2The View Details button only appears if the notification has a destination link (BR-02).
AC-03.3View Details closes the dialog and opens the destination page (BR-02).
AC-03.4A notification without a destination link — there is no View Details button (BR-02).
AC-03.5The user has no access to the destination data — the destination page takes the user to the no-access page.
AC-03.6The link is generated automatically from the notification data and must be the address of a page that actually exists in the app (BR-02). Needs confirmation: the test send produces /inventory/product/{id}, while the product detail page is currently /inventory/products/{id}/detail; the link-building rule needs to be aligned with the app’s routes. 🚧 Not yet: FE + BE

US-04 - In-app notifications

As a user, I want notifications to appear immediately while the app is open.

IDAcceptance criteria
AC-04.1Every time the app loads or reloads, it tries to connect to the realtime connection; toasts have no toggle or setting (BR-04, BR-08). 🚧 Not yet: FE
AC-04.2Connection succeeds — a new notification shows a clickable toast and updates the badge and list (BR-04).
AC-04.3Clicking the toast marks the notification as read and opens the destination page (BR-03).
AC-04.4Connection fails — no toast is shown and the user is not notified; the inbox and device notifications keep working (BR-03, BR-08).

US-05 - Device notifications

As a user, I want to receive notifications even when the app is closed.

IDAcceptance criteria
AC-05.1The Notifications toggle reflects whether this device has device notifications.
AC-05.2Turning the toggle on asks for device permission only when the user clicks it, then registers device notifications (BR-05).
AC-05.3Turning the toggle off removes the device notifications on that device (BR-06).
AC-05.4The toggle is disabled with a note if the device or browser does not support it, or permission is denied.
AC-05.5A device notification is still shown even if its content is broken, with a replacement title (BR-03).
AC-05.6Clicking a device notification while the app is closed — the app opens directly on the destination page, or on the home page if the notification has no link; the notification is not marked as read (BR-03).
AC-05.7Clicking a device notification while the app is open — the app is brought forward and opens the destination page; the notification is not marked as read (BR-03).
AC-05.8The user logs out on a device with device notifications on — that device’s notifications are removed, so they do not appear for another account (BR-06).
AC-05.9Device notifications were removed, for example after the password was changed, but browser permission is still granted — the next time the app opens, they are registered again without the user turning the toggle on (BR-07).

9. User Scenarios

RoleScenario
UserGets a toast when a notification arrives, clicks it, and goes straight to the related data page
UserReceives a notification on their phone while the app is closed
UserOpens the bell, sees the 10 latest notifications, then opens the Notifications page to mark them all as read
UserSearches for an old notification on the Notifications page with the Unread filter
UserTurns off the Notifications toggle on a shared device so they do not appear there
UserOpens the app while the realtime connection fails; no toast appears, but the notification can still be read in the inbox

10. Permissions & Actions

This feature has no permissions; every logged-in user only accesses their own notifications.

11. Notifications

Notifications is the delivery engine, not a trigger. The events that trigger notifications are recorded in the Notifications section of each feature’s PRD.

12. Dependencies

Related PRDs

  • Authentication — a login from a new device sends a notification to the account owner (BR-16 there); logging out, resetting or changing the password, and verifying a changed login email remove device notifications (BR-06). Inactive or unverified accounts follow the restrictions there (BR-01).
  • Linked Devices — device notifications are tied to the device that is logged in, and are removed when the device is revoked (BR-06).
  • Purchase Order, Goods Receipt, and other modules — potential sources of notification events; none sends them yet.

Effects on other modules

  • A feature that triggers notifications writes its destination page in the Notifications section of its own PRD; this PRD does not keep a list of destinations.
Last updated on