PRD: Device signal & notifications

Module	Device	PRD ID	PRD-MON-001
Status	Ready to dev	FEAT	MON
Epic	—	Plane	BANA-1540
Date	2026-07-17	Version	v0.2
Packages	@nx/commerce · @nx/signal	URD	MON
Surface	Backend
Owner	Phát Nguyễn

A server-side real-time notification backbone

A server-side activity-notification backbone: a worker resolves the right recipients within an organizer/merchant scope, persists a notification, and pushes it live to connected clients - with a fetch / mark-read interface behind the bell UI. Two caveats today: the ingest consumer is built but no producer feeds it, so the pipeline isn't exercised end-to-end; and the one live use case so far (inquiry-submitted) runs over a separate outreach WebSocket that bypasses the pipeline and persists nothing.

The problem this increment solves

Device Health Monitoring & Notifications (MON) needs the platform to capture activity and surface it to administrators in near real time. Today there is no server-side notification backbone: events happen across the platform, but nothing fans them out to the right users or pushes them to a live UI, so administrators cannot watch activity as it happens.

This increment builds that backbone in the real-time signal layer - an end-to-end pipeline (ingest event → worker → persisted record → live push) with recipient resolution scoped to an organizer/merchant and a stable real-time transport. Monitoring and activity surfacing ride on that transport; heartbeat / health-status reporting (URD-MON-001/002) and remote device actions (URD-MON-004/005) are tracked separately. This is also the channel PRD-DEV-001's fault-notification alert would ride on, once it gets a first producer.

1. Goals & Non-Goals

Goals

• An event-fed activity-notification pipeline: ingest → worker → persisted record → live push.
• Recipient resolution - notifications fan out to the correct users within an organizer/merchant scope.
• A stable real-time transport (rooms + topics + delivery service) with fixed channel naming, so clients subscribe against a stable contract.
• Notification read-state: an interface to fetch notifications and mark them read.
• A first end-to-end use case: inquiry-submitted live notification from the outreach domain.

Non-Goals

• Heartbeat emission and the 15-minute offline threshold (URD-MON-001/002).
• Remote deactivate / remote data wipe (URD-MON-004/005).
• The per-device health dashboard UI (the consuming client surface).
• Porting the notification toolkit out of the signal layer into a shared package.

2. Success Metrics

Metric	Target / signal
Delivery latency	Activity event → client live push in near real time (sub-second under normal load)
Recipient accuracy	Notifications reach exactly the users in the organizer/merchant scope; no cross-tenant leakage
Durability	Every emitted notification has a persisted record; read-state survives reconnect
Coverage	Inquiry-submitted live ping verified (over the separate outreach WS, not the pipeline); the pipeline awaits its first producer before it is reusable end-to-end

3. Personas & Use Cases

Persona	Goal in this feature
Administrator / Owner	See platform & device activity live, without polling
Connected client (web/app)	Receive notifications over a live connection and reflect read-state
Outreach handler	Be alerted the moment an inquiry is submitted

Core flow: an activity event lands in the pipeline → the worker resolves recipients within the organizer/merchant scope and persists a notification → the record is pushed live to connected clients → a client fetches its notifications and marks them read. An inquiry submission emits a live notification through the same transport.

4. User Stories

• As an administrator, I want activity to appear in my UI as it happens, so I can monitor the platform without refreshing.
• As a connected client, I want notifications over a live connection, so I see updates the instant they occur.
• As a connected client, I want to fetch my notifications and mark them read, so read-state is consistent across sessions.
• As an outreach handler, I want a live notification when an inquiry is submitted, so I can respond promptly.
• As the platform, I want notifications to fan out only to users in the right organizer/merchant scope, so no tenant sees another's activity.

5. Functional Requirements

#	Requirement	Status	URD ref
FR-1	Incoming activity events are ingested into the notification pipeline	Partial - the ingest consumer + worker exist, but no producer publishes to the topic, so the pipeline is not exercised end-to-end	URD-MON-003
FR-2	A worker resolves recipient users within an organizer/merchant scope	Built	URD-MON-003
FR-3	Each notification is persisted as a notification record	Built	URD-MON-003
FR-4	A real-time transport (rooms + topics + delivery service) pushes the notification to connected clients live, on a fixed notification channel	Built - encrypted WS, fixed rooms/topics. Caveat: room-subscribe authorization is stubbed (any authed user can subscribe to any room)	URD-MON-003
FR-5	An interface fetches a user's notifications and marks them read	Built	URD-MON-003
FR-6	Inquiry submission emits a live notification to interested clients	Built, but via a separate outreach WS (fire-and-forget) - it does not go through the pipeline and persists no notification record	URD-MON-003

Full requirement text and acceptance criteria live in the Device URD. This PRD references them rather than restating them.

6. Non-Functional Requirements

Area	Requirement
Tenancy & authz	Recipient resolution is scoped per organizer/merchant; notifications never cross tenant boundaries
Durability	Every live push is backed by a persisted record; read-state is retrievable after reconnect
Performance / scale	The event stream decouples ingest from fan-out; the worker absorbs bursts without blocking producers
Transport stability	Fixed channel naming, so clients subscribe against a stable contract
i18n	User-facing notification labels are bilingual (English & Vietnamese) where surfaced

7. UX & Flows

Key surfaces: the notification backbone lives in the real-time signal layer (ingest consumer, worker, delivery service, rooms, topics) with a read / mark-read interface; the inquiry path lives in the outreach domain. The consuming dashboard UI is out of scope for this increment.

8. Data & Domain

Entity	Role
Notification record	The persisted notification (recipient, payload, read-state)
Notification backbone	The ingest consumer, worker, delivery service, rooms, and topics in the signal layer
Notification channel	The fixed room/topic - the live delivery channel
Recipient resolution	Lookup of user IDs within an organizer/merchant

Conceptual only - full schema lives in the developer domain model.

9. Dependencies & Assumptions

Depends on

• Core platform - owns the notification record, the event topic + types, and recipient resolution via the membership/authorization lookup.
• Event stream - the ingest seam between activity sources and the notification worker.
• Real-time transport - the live delivery channel to connected clients.
• Outreach domain - the first event producer (inquiry submission).

Assumptions

• Activity sources publish events onto the agreed event topic.
• Organizer/merchant membership data is available for recipient resolution.
• Clients maintain a live connection and subscribe to the notification channel.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 (MON is a P2, Partial feature)
Rollout	All merchants; no feature flag
Migration	New notification record; no data migration
Launch criteria	(Pending) activity event → recipient resolution → persisted record → live push verified end to end - blocked until a producer feeds the ingest topic (a first real producer could come from PRD-DEV-001's fault notification). (Met) inquiry-submitted live ping (separate outreach WS); fetch / mark-read; read-state survives reconnect
Monitoring	Notification volume, delivery latency, live-connection health, recipient-resolution correctness

References

• URD: Device - Device Health Monitoring & Notifications - requirements (MON area)
• Related PRDs: Device registration, identity, activation & peripherals
• Module: Device - URD
• Developer: @nx/signal · @nx/outreach · @nx/core

Risks & Open Questions

Risk / question	Mitigation / status
Recipient resolution could leak across tenants	Resolution is scoped per organizer/merchant and verified against membership lookup. Open: room-subscribe authorization is stubbed - any authenticated user can currently subscribe to any recipient room
A dropped live connection could miss notifications	Every emit is backed by a persisted record; clients re-fetch read-state on reconnect
Channel naming drift between producers and clients	Naming fixed as a stable contract
Notification toolkit lives in the signal layer, not shared	Accepted for this increment; extraction to a shared package is a future consideration
MON heartbeat/health still pending	Out of scope here; this increment delivers the transport only (see §1)

FAQ

Question	Answer
Does this deliver device heartbeat / health status?	No - it delivers the real-time notification transport that monitoring rides on. Heartbeat emission and the offline threshold (URD-MON-001/002) are tracked separately.
How are recipients chosen?	The worker resolves users within the relevant organizer/merchant scope; notifications never cross tenant boundaries.
What happens if a client is disconnected when an event fires?	The notification is still persisted; the client re-fetches its notifications and read-state on reconnect.
What channel do clients subscribe to?	A fixed notification channel - a stable contract.
Why is the inquiry-submitted path here?	It is the first real-time use case proving live delivery. Note it runs over a separate outreach WebSocket (fire-and-forget) - it does not flow through the activity pipeline and persists no notification record, so it does not exercise the pipeline end-to-end.