DocHub/Ricoya/Push Notifications/Notification System Overview

Web Push notifications for all order status transitions — tested and working across Safari, Chrome, Firefox

Notification System Overview

Purpose

Push notifications alert managers, customers, and drivers when order status changes. Implements Nicky Dawda’s spec (Feb 27, 2026) covering 5 server-side scenarios plus 3 client-side polling mechanisms.

Server-Side Push Notifications

Fired from the PATCH handler in /api/admin/orders/[orderId]/route.ts using web-push library + VAPID keys.

Trigger	Recipients	Message
Order accepted	Customer + all drivers + admins	Customer: “Order accepted!” / Drivers: “New delivery available”
Order ready	Assigned driver (or all drivers if unassigned)	“Order ready for pickup” or “Order ready — needs driver”
Out for delivery	Customer	“Order on the way!”
Order canceled	Customer + all admins	Cancellation notice with reason
Driver assigned	Assigned driver	“Delivery assigned”

Client-Side Polling Notifications

Browser-based polling with sound alerts. These do not use server push — they poll API endpoints at fixed intervals.

Trigger	Recipients	Mechanism
New order placed	Managers	`usePendingOrderPings` — polls every 60s, browser notification + sound
Pending orders exist	Managers	Same hook — persistent ping every 60s while unaccepted orders remain
Unclaimed deliveries	Drivers	`useUnclaimedDeliveryPings` — polls every 60s on delivery page

Push Subscription System

Subscriptions stored in push_subscriptions table
ID format: sub_{md5(endpoint)} — unique per browser endpoint
One user can have multiple subscriptions (multiple browsers/devices)
Upsert on subscribe — same browser re-subscribing updates in place
Invalid subscriptions (410 Gone) auto-cleaned on send failure
Subscribe flow: browser PushManager.subscribe() → POST /api/push/subscribe → stored via supabaseAdmin

Testing Results (March 2, 2026)

All notification flows verified end-to-end on staging (ricoya.ipnoelp.com):

Flow	Browser	Account	Status
Driver notifications	Safari	nseanchristopher@gmail.com	Working
Customer notifications	Chrome	christophersean08@gmail.com	Working
Manager notifications	Chrome	sean@omelasai.com	Working

Safari Push Subscription Issue

Initial testing showed Safari push subscription was not saving to Supabase. The subscribeToWebPush() function wasn’t being called after initial enable because the localStorage flag was already set from a previous session. Disabling and re-enabling notifications triggered the full subscribe flow and saved the subscription correctly.

Not Yet Wired

Driver pickup confirmation (no push sent when driver confirms pickup)
Driver claim confirmation (no push sent when driver claims order)
Payment received / provider paid transitions (no notification triggers)

Key Files

File	Purpose
`src/app/api/admin/orders/[orderId]/route.ts`	PATCH handler — fires server push for status changes
`src/app/api/push/subscribe/route.ts`	Subscribe/unsubscribe endpoint
`src/app/api/push/notify/route.ts`	Manual broadcast endpoint (audience-based)
`src/lib/pushManager.ts`	`sendPushNotification()` — resolves UIDs to subscriptions, sends via web-push
`src/repositories/pushSubscriptionsRepo.ts`	CRUD for push_subscriptions table
`src/hooks/usePendingOrderPings.ts`	Manager-side 60s recurring pings for placed orders
`src/hooks/useUnclaimedDeliveryPings.ts`	Driver-side 60s recurring pings for unclaimed orders
`src/lib/customerNotifications.ts`	Customer push subscribe/unsubscribe, sound, permission
`src/lib/driverNotifications.ts`	Driver push subscribe, permission prompts
`src/components/CustomerNotificationListener.tsx`	Auto-resubscribes returning customers

Debugging Notes (Feb 27)

During initial testing, customer notifications appeared to not work. Investigation revealed the push system was functioning correctly — the issue was that the customer account had zero push subscriptions registered. The Chrome browser’s push subscription was registered under the manager account because Chrome was logged into the manager session when notifications were enabled.

Key insight: push subscriptions are per-browser, per-device. One user enabling notifications in Safari AND Chrome creates two separate subscription rows in , both tied to their . The system sends to all subscriptions for the target UID.

The manager notification modal’s “Test Alerts” button only fires a local browser Notification API test — it does NOT register a server-side push subscription. The actual subscribe flow is triggered from the orders board notification enable button.

Debugging Notes (Feb 27)

During initial testing, customer notifications appeared to not work. Investigation revealed the push system was functioning correctly — the issue was that the customer account had zero push subscriptions registered. The Chrome browser push subscription was registered under the manager account because Chrome was logged into the manager session when notifications were enabled.

Key insight: push subscriptions are per-browser, per-device. One user enabling notifications in Safari AND Chrome creates two separate subscription rows in push_subscriptions, both tied to their user_uid. The system sends to all subscriptions for the target UID.

The manager notification modal “Test Alerts” button only fires a local browser Notification API test — it does NOT register a server-side push subscription. The actual subscribe flow is triggered from the orders board notification enable button.