Notification triggers

Event -> guard -> fanout -> surface

6 trigger families 5 pipeline stages 6 delivery surfaces

Channel / DM composer

message.created

Message

Source event

  • new DM
  • private/event channel message
  • thread reply

Trigger logic

  • parse channel mode
  • resolve thread participants
  • detect broad channel push

Recipient guard

  • can view channel
  • sender removed
  • HFC channel suppresses push

Fanout

  • Feed.track
  • Push.notify
  • unread_counts_updated

User surface

  • inbox row
  • device push
  • badge refresh

A new message can produce feed rows, unread counters, desktop alerts, and push alerts depending on audience and channel mode.

Run trace message.created
ChatDelivery message payload persisted
Feed notification row written for visible recipients
Push device tokens loaded and delivery rows queued
Sockets unread counts broadcast to active clients
Payload route deep link + analytics
tap target channel, DM, or thread route
socket topic notifications:{user_public_id}
analytics queued, accepted, received, opened
Guards

Before a trigger becomes a notification

Access first

Channel, story, work, and space visibility are checked before fanout.

Actor excluded

The person who caused the event is removed from recipient lists.

Dedupe paths

Explicit mentions, participants, and broad recipients collapse into one route per user.

Presence aware

Push is biased toward useful moments while active clients get socket updates.

Quiet channels

HFC and muted paths suppress noisy channel push alerts.

Delivery measured

Push deliveries record queued, accepted, failed, received, and opened states.

Surfaces

Where the user sees the result

Inbox row

Feed notification persisted and broadcast to notifications:{user_public_id}.

Device push

FCM/APNs payload with badge data, delivery id, and deep link.

Foreground banner

Active clients can surface priority events without leaving the current screen.

Desktop local

Desktop clients turn realtime events into OS-level local notifications.

Unread badge

Unread counts refresh channel state, DM cards, and app icon badges.

Email

Account lifecycle and inactivity messages go through the email adapter.

Source map

Backend and client paths that trigger notification behavior

ChatDelivery message, mention, thread reply, unread count refresh
Feed notification row persistence and realtime socket broadcasts
Push FCM payloads, push delivery rows, story and reminder pushes
AccountNotifications welcome, password, forgot-password, inactivity email
NotificationsNotifier recent/live inbox state, unread counters, badges
PushService token registration, foreground banners, routing, delivery tracking