Architecture

Components

Component	Path
OneSignal client (REST v11)	`lib/integration/onesignal/onesignal.client.ts`
Dispatcher (enqueue)	`lib/notification/notification-dispatcher.ts`
Registry `(channel,type)`	`lib/notification/notification-registry.ts`
Targeting (`external_id`)	`lib/notification/notification-targeting.ts`
Unified consumer route	`app/api/queue/notification/route.ts`
Per-channel handlers	`lib/queue/notification/handlers/*.handler.ts`

Queue payload contract

Every message on the notification topic satisfies NotificationQueuePayload:

{
  "category": "payment",       // marketing | payment | system | transactional
  "channel": "push",           // in_app | live_activity | push | sms
  "correlation": "corr-uuid",  // producer → queue → handler traceability
  "data": { "debtId": "…" },   // channel/type-specific content
  "queue_event_id": "uuid",    // idempotency key
  "type": "PAYMENT_FAILED",    // registry type
  "user": "auth-user-uuid"      // target; used as OneSignal external_id
}

The consumer uses channel to segment queue_event.event_type (vercel_queue.notification.<channel>) and type to pick the handler.

Dispatcher usage (producers)

import { notificationDispatcher } from "@/lib/notification/notification-dispatcher";

// Best-effort enqueue: gating + send.
await notificationDispatcher.enqueue({
  category: "payment",
  channel: "push",
  correlation,
  data: { amount, debtId },
  type: "PAYMENT_FAILED",
  user: authUserId,
});

// Durable enqueue (outbox): persists a replayable queue_event before the send.
await notificationDispatcher.enqueueDurable({ /* same params */ });

Use enqueueDurable for critical notifications (payment / system / transactional) and enqueue for the rest. Bulk sends use enqueueBulk with per-batch throttling.

First real producer

The failed-payment push (PAYMENT_FAILED) is wired end-to-end: notifyPaymentFailed resolves the account members and enqueues one payment push per user when a Toku transaction.failed webhook records a failed attempt. Because payment is non-suppressible, preference gating never discards it, and any enqueue failure is logged without breaking the webhook.

Adding a new type

Add it to NOTIFICATION_TYPES in notification-registry.ts.

Define its data

Extend notification-queue-types.ts if the type needs its own fields.

Optional override

Produce

Call notificationDispatcher.enqueue(...) from the business service.

No change to the consumer route or vercel.json is needed for a new type within an already-supported channel.

Get Started

API Documentation

OAuth & Identity (IdP)

Monitoring & Infrastructure

Realtime (Pusher)

Notifications (OneSignal)

Components

Queue payload contract

Dispatcher usage (producers)

First real producer

Adding a new type

​Components

​Queue payload contract

​Dispatcher usage (producers)

​First real producer

​Adding a new type

Components

Queue payload contract

Dispatcher usage (producers)

First real producer

Adding a new type