Notification Routing

Backend architecture for multi-channel notification delivery.

Runtime model: Container-first (persistent Bun process), with Vercel serverless as compatible fallback.

Routing Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                         NotificationService.send()                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Input: { userId, type, title, body, entityRef?, actionUrl?, groupKey? }    │
│                                                                              │
│  1. Create in-app notification record (always)                              │
│  2. Load user settings + connected channels                                  │
│  3. Apply routing rules:                                                     │
│     - Security type → force email (cannot disable)                          │
│     - Check settings matrix for each channel                                │
│     - Skip disconnected/inactive channels                                   │
│  4. Create delivery records in outbox                                       │
│  5. Trigger delivery:                                                        │
│     - Container: notify in-process worker (immediate pickup)                │
│     - Vercel: emit Inngest event "notification/queued"                      │
│                                                                              │
│  Output: { notificationId, queuedChannels[] }                               │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Provider Interface

Each channel provider implements a common interface:

Delivery Result

Provider Implementations

Email Provider (Resend)

Telegram Provider (Bot API via fetch)

Discord Provider

Critical: Discord rate limits are NOT hard-coded. Always parse:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Rate Limiting Strategy

Per-Provider Limits

Implementation Options

Recommendation: Database-backed rate tracking for container (simple, persistent). Inngest's rateLimit for Vercel deployments. Both use the same outbox table.

Outbox Pattern

Store pending deliveries in database before async processing:

Container runtime:
┌─────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  Sync       │────▶│ notification_       │────▶│  In-process      │
│  Handler    │     │ deliveries (outbox) │     │  Worker          │
└─────────────┘     └─────────────────────┘     │  (setInterval)   │
      │                       │                  └──────────────────┘
      ▼                       ▼                       │
 In-app notif           Delivery          External providers
   created              persisted            called async

Vercel serverless:
┌─────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  Sync       │────▶│ notification_       │────▶│  Inngest /       │
│  Handler    │     │ deliveries (outbox) │     │  Vercel Cron     │
└─────────────┘     └─────────────────────┘     └──────────────────┘

Why Outbox?

Delivery Processing (Runtime-Adaptive)

The outbox table is the contract. Who processes it depends on the runtime.

Container: In-Process Worker (Primary)

The existing job runner at src/lib/server/jobs/scheduler.ts already supports setInterval-based background jobs. Add a notification-delivery job:

Vercel: Inngest (Fallback)

When deployed on serverless, Inngest provides step-level durability:

Vercel: Cron Sweep (Safety Net)

Regardless of runtime, a periodic cron job sweeps for any outbox records stuck in pending state (belt-and-suspenders):

Retry Configuration

Error Handling

Error Classification

Channel Deactivation

When a channel fails permanently:

1. Set is_active = false in channel table
2. Store error message in last_error column
3. Send notification via other channels: "Your {channel} is disconnected"
4. Surface in settings UI with "Reconnect" button

Delivery Tracking

notification_deliveries Table

Retention Policy

Clean up via scheduled job (daily) — runs as setInterval in container, Vercel cron on serverless.

Module Structure

src/lib/server/notifications/
├── index.ts                # Re-exports public API
├── service.ts              # NotificationService.send() — single entry point
├── router.ts               # Preference resolution, channel selection
├── queries.ts              # DB queries (getUnread, markRead, etc.)
├── types.ts                # NotificationType, DeliveryResult, etc.
├── stream.ts               # SSE: notifyUser() + connection registry (container only)
├── providers/
│   ├── index.ts            # Provider registry (getProvider by channel)
│   ├── types.ts            # Provider interface
│   ├── email.ts            # Resend provider
│   ├── telegram.ts         # Raw fetch() to Bot API
│   └── discord.ts          # Discord REST provider
├── outbox.ts               # Delivery record management
└── inngest/                # Only used on Vercel deployments
    ├── client.ts           # Inngest client setup
    └── functions/
        └── deliver.ts      # notification/queued handler

Runtime Detection

// Use the same pattern as existing job scheduler
const IS_SERVERLESS = !!process.env.VERCEL;

// In service.ts, after outbox write:
if (IS_SERVERLESS && inngest) {
  await inngest.send({ name: 'notification/queued', data: { notificationId } });
}
// On container, the in-process worker picks up pending records automatically

Related

• ./channels.md - Channel connection flows
• ./schema.md - Database tables
• ../middleware.md - Hooks integration
• ../../stack/notifications/ - Provider details