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
- 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).
- 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).
- 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
- Device Notification Appears — If the Notifications toggle is on, the notification appears on the device even when the app is closed (BR-04).
- Choose How to Open — The user opens the notification through the bell or the Notifications page, or directly from a toast or device notification.
- 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).
- Destination Page — The user lands directly on the related data without looking for it (BR-02).
- 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
- 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
| Status | Description | Next |
|---|---|---|
| Unread | The notification has not been opened and is highlighted in the list | Read |
| Read | The 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 Notification | Browser Push Notification | |
|---|---|---|
| WebSocket | Yes | No |
| How it works | The 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 sonner | Service Worker (public/sw.js), Push API (PushManager), and Notification API for permission |
| User setting | No 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 |
| Authorization | Endpoint /api/broadcasting/auth | Subscriptions are registered through /api/auth/notifications/subscriptions |
| If not delivered | The toast does not appear while the connection is down; the notification stays in the inbox | The 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
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Title | Text | — | Built from the event | First line of the notification |
| Content | Text | — | Built from the event | Description of the notification |
| Created At | Date & Time | — | When the notification is created | Shown relatively, for example “5 minutes ago” |
| Read At | Date & Time | — | Empty | Filled when the notification is opened (BR-03) |
| Destination | Text | — | Determined from the event | Address 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
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Device | Ref. Device | — | Taken from the login when device notifications are turned on | Ties the notification to a Linked Device (BR-06) |
| Subscription Data | Text | Yes | Given by the browser when allowed | Technical 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
| Part | Example Value | Component |
|---|---|---|
| Count Badge | 12, or 99+ | Badge |
| Tab | All, Unread | Tabs |
| List | 10 latest notifications | List Item, with module icon, title, and relative time |
| View All Link | — | Link to the Notifications page |
Actions: View All.
7.2 Notifications Page
| Field | Control | Behavior |
|---|---|---|
| Tab | All/Unread toggle (in the header, as icons) | Kept when the page reloads |
| Search | Text Input | Kept when the page reloads; searches the title and content |
| List | List Item, loaded in batches | Load More button |
Actions: Mark All as Read, on the same row as the search.
7.3 Detail Dialog
| Field | Component |
|---|---|
| Title | Text |
| Content | Text 🚧 Not yet: FE |
| Time | Text, relative |
| View Details Action | Button, only shown if the notification has a destination link (BR-02) |
Actions: View Details, Close.
7.4 Notification Settings
Available in the header settings.
| Field | Control | Behavior |
|---|---|---|
| Notifications | Toggle | Controls 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.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | The bell shows an unread count badge; more than 99 is shown as “99+”. |
| AC-01.2 | The popover shows the 10 latest notifications with All and Unread tabs. |
| AC-01.3 | The View All link opens the Notifications page; clicking an item closes the popover and opens the detail dialog. |
| AC-01.4 | Empty states: “No notifications yet” or “No unread notifications”. |
| AC-01.5 | A 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.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | The All and Unread tabs and the search keyword are kept when the page reloads; search matches the title and content. |
| AC-02.2 | The list loads in batches of 15 with a Load More button. |
| AC-02.3 | The Mark All as Read button marks all the user’s notifications as read and updates the list and badge (BR-03). |
| AC-02.4 | Unread 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.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | Clicking 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.2 | The View Details button only appears if the notification has a destination link (BR-02). |
| AC-03.3 | View Details closes the dialog and opens the destination page (BR-02). |
| AC-03.4 | A notification without a destination link — there is no View Details button (BR-02). |
| AC-03.5 | The user has no access to the destination data — the destination page takes the user to the no-access page. |
| AC-03.6 | The 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.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | Every 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.2 | Connection succeeds — a new notification shows a clickable toast and updates the badge and list (BR-04). |
| AC-04.3 | Clicking the toast marks the notification as read and opens the destination page (BR-03). |
| AC-04.4 | Connection 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.
| ID | Acceptance criteria |
|---|---|
| AC-05.1 | The Notifications toggle reflects whether this device has device notifications. |
| AC-05.2 | Turning the toggle on asks for device permission only when the user clicks it, then registers device notifications (BR-05). |
| AC-05.3 | Turning the toggle off removes the device notifications on that device (BR-06). |
| AC-05.4 | The toggle is disabled with a note if the device or browser does not support it, or permission is denied. |
| AC-05.5 | A device notification is still shown even if its content is broken, with a replacement title (BR-03). |
| AC-05.6 | Clicking 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.7 | Clicking 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.8 | The 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.9 | Device 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
| Role | Scenario |
|---|---|
| User | Gets a toast when a notification arrives, clicks it, and goes straight to the related data page |
| User | Receives a notification on their phone while the app is closed |
| User | Opens the bell, sees the 10 latest notifications, then opens the Notifications page to mark them all as read |
| User | Searches for an old notification on the Notifications page with the Unread filter |
| User | Turns off the Notifications toggle on a shared device so they do not appear there |
| User | Opens 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.