> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/health/design/architecture/field-app-architecture/ui-packages/push-notification.md).
# Push Notification
### Notifications Integration
Push notifications are wired end-to-end in HCM v2.1 for both Stock and HF Referral flows. A single notification handler now dispatches to the right flow based on payload type, with token registration on login and unregister on logout so a device only receives notifications relevant to the currently signed-in user / project.
#### What's new across both flows
* **Notification token lifecycle.** The device's push token is registered against the user on login (via the new notification-token repository) and **unregistered on logout**, so a re-used handset doesn't keep receiving notifications meant for a previous user.
* **Unified payload handler.** A single `NotificationData` payload class parses incoming notifications and routes them — stock-related events go through the stock handler, referral-related events go through the referral handler. Adding a third flow in future is a payload-type addition, not a new pipeline.
* **Boundary-scoped delivery.** Notifications are scoped to the worker's assigned boundary, matching how stock and referral data are already scoped — workers only see events for their own LGA / facility / village.
* **Notification-triggered downsync.** Incoming notifications kick a targeted downsync for the related entity (stock dispatch or HF referral), so the worker sees the new record on next list refresh without waiting for the periodic sync.
#### Notifications Flow — UML Sequence Diagram
#### Stock Notifications
When the warehouse manager / LGA dispatches stock toward a facility or team, the receiver-side user gets a push notification announcing the inbound transaction. The notification carries enough payload to trigger an immediate downsync of just that dispatch.
**What field workers see:**
* A push notification on the receiver's device the moment stock is dispatched their way ("New stock dispatch from — ").
* Tapping the notification opens the receive list with the new inbound transaction already pulled and visible at the top.
* The receive list's dedup (via the wrapper-level `notExists` filter — see §1) correctly hides the inbound if the user has already received it via QR scan, so notifications can't cause a duplicate entry.
**What triggers it:**
* A new `DISPATCHED` stock row created by a sender that names the recipient (by `receiverId` or by `boundaryCode` for boundary-routed flows).
* Stock balance updates that flip a downstream worker's available quantity (informational notifications — opt-in via campaign config).
***
#### HF Referral Notifications
When a facility raises a referral against a beneficiary, the field worker assigned to that boundary gets a push notification so the referral history is current the next time the beneficiary is visited.
**What field workers see:**
* A push notification when a facility-side referral is created for a beneficiary in the worker's boundary ("New referral raised for at ").
* Tapping the notification opens the beneficiary's referral history, with the new facility-raised referral merged into the local list
* Pagination over high-volume referral lists works correctly — the notification-triggered downsync respects the same paged pull as the periodic downsync.
**What triggers it:**
* A new HF Referral created on the console / facility side that maps to the worker's assigned boundary.
* Multi-cycle re-entry: when a beneficiary is re-evaluated in a new cycle and a referral is raised, the worker is notified for the new cycle's referral specifically (no stale prior-cycle alerts).
* Referral notifications carry the referral's reason(s) so the worker has context before opening the record — multi-reason cases are preserved end-to-end
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.digit.org/health/design/architecture/field-app-architecture/ui-packages/push-notification.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
