Notifications

Notifications

When to use: Adding a notification kind / group / channel, touching the notifications table or users.notification_preferences, wiring a new source event into the notification pipeline, or debugging in-app / email delivery.

Always read dev-docs/notifications.md for the full picture before editing. This skill is the action-oriented summary.

Vocabulary (and what NOT to confuse)

Four orthogonal axes — keep them straight:

AlertIncidentKind (issue.new / issue.regressed / issue.escalating) is a fifth axis — it lives inside the incident.* payload and gates the producer step at the project level. It is not a NotificationKind. The mapping today: issue.new and issue.regressed → incident.event (one-shot, endedAt = startedAt); issue.escalating → incident.opened + later incident.closed (sustained, endedAt transitions from null). The producer derives the notification kind from incident.endedAt, so adding a new sustained or eventful alert kind is purely a @domain/alerts change.

Pipeline at a glance

source domain event → domain-events worker
                    → notifications:request-<group>-notifications
                    → notifications:create-notification (one per recipient)
                    → notification-email:send (if user prefs allow)

Project deletion cascades via a separate path: ProjectDeleted → notifications:delete-by-project.

Producers compute everything; consumers act idempotently. See dev-doc for details.

Adding a new kind (existing group)

1. Add the kind to NOTIFICATION_KIND_META (packages/domain/notifications/src/entities/notification.ts) with { group, payload }.
2. Define the payload schema in the same file. Keep it flat — no nested event discriminator.
3. Extend buildIdempotencyKey (helpers/idempotency-key.ts) with the new kind. Pattern: ${kind}:${naturalEntityId} if there is one, ${kind}:${entityId}:${eventTimestamp} when the same entity can legitimately fire again (the unique index is permanent), else ${kind}:${generateId()}.
4. Add per-channel renderers (TS will fail the build until each is present):
   • In-app: apps/web/src/routes/_authenticated/-components/notifications/renderers/<kind>.tsx + entry in notification-item.tsx's dispatch.
   • Email: packages/domain/email/src/templates/notifications/<kind>/index.tsx + entry in registry.ts. The renderer is an Effect — it can yield* any services it needs (e.g. WrappedReportRepository for wrapped.report). If the renderer needs services beyond SqlClient, wire the matching *Live layer into the email worker's rendererLayer in apps/workers/src/workers/notification-emailer.ts. Renderers that only need payload + context use Effect.tryPromise(() => buildHtml(...)).
5. If the kind has its own source flow (not just wrapping an existing one):
   • Add a request-<kind>-notifications task to the notifications queue topic.
   • Write requestXxxNotificationsUseCase in @domain/notifications.
   • Route the source domain event in apps/workers/src/workers/domain-events.ts.
   • Add a handler in apps/workers/src/workers/notifications.ts.
6. If the kind is tied to a project, set projectId on each request so the ProjectDeleted cascade cleans it up.
7. Tests alongside each use case + each renderer.

No user-preferences UI change needed. The new kind inherits the group's existing toggle.

Adding a new topic (sub-toggle inside a group)

Reach for a topic when a group's existing switch is too coarse — the recipient wants this group but not this slice of it. A topic is one entry in NOTIFICATION_TOPICS + NOTIFICATION_TOPIC_META and one entry in the owning group's topics list (all in packages/domain/shared/src/notification-preferences.ts); both settings UIs render it from that meta with no further edits.

• defaultEnabled: true is the normal case — the topic behaves opt-out, matching every other default in the system.
• defaultEnabled: false makes it opt-in on both channels at once. admitsTopic is the single resolver behind shouldSendEmail and the worker's Slack fan-out, so one flag covers email, Slack, and both settings screens. Use it for topics that fire on routine activity a busy project would read as spam (signal.reprioritized fires on every priority increase).
• Read checked in the UIs through admitsTopic(...), never ?? true — a hardcoded fallback silently shows an opt-in topic as on.
• A topic only filters delivery. The in-app bell row is always written, so a muted topic still shows up in the feed.
• A topic filter is the last line of defence, not the first. If a whole class of source events is never worth announcing, guard the outbox write instead — updateSignalTriageUseCase only emits SignalReprioritized for priority increases, so a downgrade costs no outbox row, no queue hop, and no producer run. Filtering downstream would burn all three to reach the same silence.

Adding a new group

A new group adds a new user-visible preferences toggle and (optionally) a new project-level gate.

1. Add the group to NOTIFICATION_GROUPS and NOTIFICATION_GROUP_META in packages/domain/shared/src/notification-preferences.ts (groups today: signals, monitors, wrapped_reports, agent_score, custom_messages, personal, destinations, billing). notificationPreferencesSchema is built from NOTIFICATION_GROUPS and auto-extends. Set slackRoutable on the meta: non-routable groups (e.g. personal — single-recipient kinds) are hidden from the Slack routes settings, rejected by the route-config server fns, and skipped by the worker's Slack fan-out; the Slack renderer registry still needs a (stub) entry because it is exhaustive.
2. The user-prefs settings page (apps/web/src/routes/_authenticated/projects/$projectSlug/settings/account.tsx) iterates NOTIFICATION_GROUPS to render toggles — the new group appears automatically with its label/description from the meta.
3. Add at least one kind to the new group (use the "Adding a new kind" steps).
4. Project-level gate (optional) — only if the new group should be opt-out-able per project:
   • Add a slot to notificationsSettingSchema in packages/domain/shared/src/settings.ts.
   • Define the inner shape (per-kind, per-target, simple boolean — whatever's useful at the project level).
   • Add a helper next to isIncidentNotificationEnabled and call it from the new producer use case before fan-out.
   • Update the API ProjectSettingsSchema in packages/operations/src/operations/projects.ts and regenerate openapi/mcp:

     pnpm --filter @app/api openapi:emit
     pnpm --filter @app/api mcp:emit

   • Wire the new toggles into apps/web/src/routes/_authenticated/projects/$projectSlug/settings.tsx.
5. Tests: extend request-*-notifications.test.ts patterns; add a cross-group preference test (group X off, group Y still on).

Group keys are persisted in users.notification_preferences jsonb — picking a stable group key matters more than a stable label (the label is NOTIFICATION_GROUP_META[group].label and can change freely).