Notification Engine

Every notification in the Partners Portal goes through one dispatcher. It resolves a per-event routing config, fans out to in-app, email, and Slack, and records each attempt so a failure is visible rather than silent.

Backed by real code:

• Event registry — apps/partners/lib/notifications/events.ts
• Route resolution + recipients (pure) — apps/partners/lib/notifications/resolve.ts
• Dispatcher — apps/partners/lib/notifications/dispatch.ts
• Channel adapters — apps/partners/lib/notifications/channels/{in-app,email,slack}.ts
• Delivery records + retry policy — apps/partners/lib/notifications/deliveries.ts
• Tables — notifications, notification_routes, notification_deliveries in apps/partners/lib/db/schema.ts
• Read + mark-read actions — apps/partners/lib/actions/notifications.ts
• Admin surface — apps/partners/app/(admin)/admin/notifications/
• Retry cron — apps/partners/app/api/cron/notification-retry/route.ts

Why this exists#

Before the engine, the portal had two disconnected delivery paths hand-wired at every call site: the in-app notifications table and eight Resend senders. Three consequences:

1. Nobody at Matters.AI was ever notified of anything. Every notification was clerkOrgId-scoped to a partner org. Deal registration emailed only session.email — the partner who had just submitted the deal. This left the WEB-1 requirement "notify the internal channel/sales team of new registrations" unmet from 2026-06-01.
2. Five events fired nothing at all — deal registration, deal update, extension request, MDF submission, and failed Salesforce sync retries.
3. Failures were invisible. Every sender was called .catch(() => undefined), so a Resend outage was completely silent.

The event registry#

NOTIFICATION_EVENTS in lib/notifications/events.ts is the single source. Three consumers read it — the routing table, the admin matrix, and the dispatcher — so adding an event is one entry rather than four edits.

Each entry declares a dotted key, a label, an audience, its defaultChannels, and an inAppType.

deal.registered is the only event defaulting to all three channels — it is the one the requirement names.

content.published is deliberately absent. Content documents are global, not org-scoped, so a partner in-app row could only be addressed to the uploader's org — an internal admin's — which is both the wrong audience and misleading. Announcing new content stays with Broadcast.

Two new notifications.type values. The column was documented as five values; access_request and sync were added for events the original five cannot describe. The column is free text, so no migration was needed — but every NotificationType must have an icon in NotificationBell, which a registry test asserts.

The routing table#

notification_routes, one row per event:

Seeding is lazy, not a migration. resolveRoute(key, stored, envWebhook) returns the stored row if present, otherwise the registry default. A missing row therefore can never mean "notification silently disabled" — the worst case is that defaults apply. Rows are written on first admin save.

At least one channel is mandatory. A Zod refinement in RouteConfigSchema rejects an empty enabledChannels, enforced in the server action. The UI additionally disables the last remaining checkbox, but the server is the boundary.

A stored channel that is not a real channel is filtered, not trusted — a retired channel name left in a row cannot crash the dispatcher.

Slack uses an Incoming Webhook, not a bot token: no OAuth flow, no scopes, no token refresh, no channel picker — a single URL posting to one channel, which is the entire requirement. The webhook host is pinned to hooks.slack.com by schema refinement, so a mistyped or hostile URL cannot receive internal deal data. SLACK_WEBHOOK_URL is an optional env fallback used when a route has no per-event override.

The dispatcher#

notify({
  event: "deal.registered",
  partnerOrgId,        // omit for internal-only events
  partnerEmail,        // partner contact for the email channel
  excludeClerkUserId,  // excluded from the partner in-app fan-out
  title,
  body,
  href,
});

Resolves the route, derives targets, fans out, records each attempt.

• Promise.allSettled, not all — one dead channel must not suppress the others.
• notify() never throws. The whole body is wrapped; a notification failure must not roll back the business action that triggered it. Every gap-event call site uses void notify(...) for the same reason — a Slack outage cannot fail a deal registration.
• Audience boundaries are never crossed. deriveTargets sends to a partner inbox only for partner/both events and to internal recipients only for internal/both. An address that is both the partner contact and an internal recipient is deduplicated.
• No self-notify on the partner fan-out — the actor already knows what they did. It does not apply to the internal fan-out: an internal recipient who happens to be the actor is wearing a different hat.

Structure, and why#

Route resolution, recipient derivation, and retry policy are pure functions in resolve.ts and deliveries.ts — no DB, no network. Only three thin adapters touch I/O. This keeps the interesting decisions testable under the suite's environment: "node": the repo has no @vitejs/plugin-react and is missing @testing-library/dom, so anything requiring React to exercise would mean adding test infrastructure to cover logic that does not need it.

The legacy shims#

sendNotification and notifyOrgMembers in lib/notifications.ts are now thin wrappers over notify(), with unchanged signatures, so the ~15 pre-existing call sites kept working without a flag day. New code should call notify() with a registry event key.

"use server" constraint. dispatch.ts, lib/notifications.ts, and lib/actions/notification-routes.ts carry the directive, where every runtime export must be an async function. This is why LEGACY_TYPE_EVENT lives in events.ts rather than next to the shims that use it: a constant exported from a "use server" module type-checks and runs in dev, then fails next build.

The audience model#

notifications.audience is "partner" | "internal", defaulting to "partner" so every pre-existing row kept its behaviour with no backfill.

Why a column rather than org scoping. requirePartnerSession() returns clerkOrgId: orgId ?? "" for internal staff — the currently active Clerk org, not MATTERS_CLERK_ORG_ID. Internal users switch orgs, so an internal user sitting in a partner's context would have read that partner's inbox.

getNotifications, getUnreadCount, markNotificationRead, and markAllRead all share one visibilityPredicate():

• Internal viewer — audience = 'internal' rows, regardless of active org.
• Partner viewer — audience = 'partner' rows in their own org only.

Both keep the clerkUserId clause (clerkUserId IS NULL OR clerkUserId = me). That clause exists because a user-targeted notification would otherwise leak to every member of an org; widening it to make internal delivery work would have re-opened exactly that bug, which is why the audience column exists instead.

Internal status is resolved from accountType via isInternalTier, not from session.partnerType. The latter is Salesforce-sourced metadata on a partner row and is not a trustworthy authorization signal.

The admin bell was inert#

app/(admin)/layout.tsx previously rendered <Navbar notifications={[]} unreadNotifications={0} /> — both hardcoded — while the portal layout genuinely fetched. Writing internal rows would have changed nothing visible, so the layout now fetches like the portal does.

Delivery records and retry#

notification_deliveries holds one row per attempt: eventKey, channel, target, audience, ok, error (truncated to 500), durationMs, attempt, nextRetryAt, and the payload for replay.

Retry is deliberately asymmetric:

• Internal failures retry — capped backoff across 5 attempts (~1m, 4m, 15m, 1h, 4h). A missed CRO alert is the failure this engine exists to prevent.
• Partner-facing failures never retry. They are recorded and surfaced, but the portal holds no provider-side idempotency key, and a duplicate partner email is worse than a missed one. computeNextRetryAt returns null for them, so they never carry a nextRetryAt at all.

/api/cron/notification-retry runs every 15 minutes, authorised by the same constant-time CRON_SECRET bearer comparison the two existing crons use. It:

• selects up to 50 rows where ok = false AND nextRetryAt <= now(),
• clears nextRetryAt before replaying, so a throwing send cannot compound on the next tick,
• writes a new delivery row at attempt + 1 rather than mutating the original, preserving the failure history,
• narrows the stored jsonb payload rather than trusting its shape.

A dedicated route rather than piggybacking: lead-lifecycle-sweep runs daily at 02:00 — far too slow for a deal alert — and revalidate-partner-status has an unrelated concern and its own time budget.

Admin surface#

/admin/notifications, gated by requireSuperAdminSession(). Super-admin only: requireAdminSession (read tier) and requireAdminWriteSession are both too permissive for deciding who receives internal deal alerts.

• Matrix — one row per registry event: channel toggles, plus the internal-email list and Slack webhook for events with an internal audience. A partner-only event has no internal recipients by construction, so those controls are not rendered. Rows still on the registry default are marked · default.
• Test send — per channel, dispatches a clearly-labelled synthetic notification and reports the outcome read back from the delivery record. This is how a super admin validates a webhook without waiting for a real deal.
• Failures panel — the 20 most recent failed deliveries, distinguishing not retried (partner) from exhausted (internal).
• Audit — every save writes notification_route.updated to activity_log with a { field: [before, after] } diff over only the fields that actually changed, matching the opportunity.admin_field_override shape.

Broadcast#

The admin announcement channel: /admin/broadcast composes a message to all partner orgs or one tier, and emits broadcast.sent per org. The tier audience now resolves from partner_profiles.partner_tier (the org-level source of truth) — it previously filtered per-member partner_sessions rows, so an org whose member rows disagreed had its audience silently split. See Admin Navigation & Org Hub. It remains the right tool for anything global — including new content — because it targets every partner org explicitly rather than inferring one from a call site.

Setup#

One schema step, recorded in apps/partners/PENDING_TASKS.md §12:

pnpm --filter @matters/partners db:push

db:push needs a TTY. All three changes are additive. Until it runs, notify() fails against the missing tables — and because it swallows its own errors, the visible symptom is simply that no notification arrives while the business action still succeeds.

SLACK_WEBHOOK_URL is optional; a per-event webhook set from /admin/notifications takes precedence.

Known limitation#

The dispatcher's fan-out has no integration test. Its pure parts — resolveRoute, deriveTargets, computeNextRetryAt, slackPayload, audienceFilter — are covered, but the orchestration itself is verified by manual check, because the repo has no DB or Clerk test harness.