marketplaces/docs/superpowers/specs/2026-08-15-admin-purchase-notifications-design.md

Admin purchase notifications — design

Status: Approved Date: 2026-08-15 Related backlog item: #7 (marked ВАЖНО — important)

Problem

Admin has no signal when a purchase happens on the marketplace. Orders only surface if someone manually opens the Orders list and refreshes. Backend exposes no WebSocket/SSE (confirmed in BACKEND-API-REFERENCE.md:20 — every "live" feature today, e.g. payment status, is plain polling), so this has to be poll-based like the rest of the app.

Architecture

AdminOrderWatcherService (new, providedIn: root, admin-scoped)

• Polls AdminOrdersLocalGateway.loadOrders() (sorted createdAt desc, already the default sort) on an interval.
• Diffs the newest order's id/createdAt against the last-seen value, kept in memory and persisted via LocalStorageService (survives page reload, same pattern as AdminPreferencesService).
• On finding order(s) newer than last-seen: fires one toast per new order and increments an unreadCount signal.
• Started once at the admin shell root, so it keeps polling regardless of which admin page is open.

Poll interval

• Editable by admin, default 15s.
• Setting lives in the same admin-settings page as currency rates (admin-settings-page.component.ts), persisted via LocalStorageService.

Toast delivery

• Reuses the existing UserNotificationService / FloatingNotificationsComponent (already global — providedIn: root, mounted once in app.html). No new toast UI.
• UserNotification gains an optional route: string[] field.
• FloatingNotificationsComponent gets a click handler: navigate to route (if set) then dismiss.

Badge — reuses existing topbar bell

admin-layout.component.html:141-157 already has an unused bell icon + dropdown panel (currently hardcoded to always show "no notifications"). Wire the watcher's data into it instead of adding a new indicator:

• unreadCount signal (from AdminOrderWatcherService) rendered as a badge on the bell icon (admin-layout__icon-button).
• Opening the panel (notificationsOpen(), already wired to the bell click) lists the unread new orders instead of the static "notificationsEmpty" text.
• Opening the panel marks all currently-known orders as seen → badge resets to 0 (same trigger AdminLayoutComponent.toggleNotifications() already has).

Click behavior

• Toast click → /admin/orders/:id (the new order's detail page).
• Clicking an order row inside the bell panel → same, then closes the panel.

Data flow

AdminOrderWatcherService (interval timer)
  -> AdminOrdersLocalGateway.loadOrders()
  -> diff against last-seen order id/createdAt (LocalStorageService)
  -> new order(s) found?
       -> UserNotificationService.show(message, 'info', { route: ['/admin/orders', id] })
       -> unreadCount.update(n => n + 1)
  -> admin clicks toast/badge -> router navigate -> orders-list visit resets unreadCount

Error handling

Poll failures are silent/logged only (console.error), consistent with existing polling code (payment status polling in cart.component.ts). No toast spam on transient network errors — watcher just retries on the next interval.

Out of scope

• Native OS push notifications (tab not focused) — user explicitly chose in-app toast/badge only, not browser Notification API.
• Sound alerts — not selected.
• Telegram/email alerts to staff — not selected, would need backend bot/mail integration.