Notifications & realtime
The bell, event types, the SSE feed and how writes become notifications.
Notifications & realtime
The rule
Every dashboard mutation that someone else should know about creates a notification row. That row is then pushed to open browsers. There is no separate "event bus" to configure.
Event types
info, task, sprint, mention, wellbeing, gamification, ai, system and cms. The type drives the icon and colour in the bell feed and is the value you filter on.
Delivery
- GET /api/notifications returns your feed, newest first, with read state and an in-app link.
- GET /api/notifications/live is a Server-Sent Events stream. The browser subscribes once and receives new rows as they are written; this is what makes the bell update without a refresh.
- PATCH /api/notifications/<id> marks one read; DELETE removes it.
If the stream disconnects (sleep, network change) the client resubscribes and falls back to a poll so nothing is silently lost.
Writing a notification from your own code
Use createNotification({ userId, type, title, body, link, metadata }) from lib/notifications.ts, or notifyMany(ids, payload) for a group. link should be an in-app route such as /dashboard/tasks so a click lands somewhere real.
Two levels of control
- Workspace switches in /dashboard/team/settings decide whether an event type is recorded at all (memberJoined, memberRemoved, profileUpdated, roleChanged, wellbeingAlert).
- Personal preferences in /dashboard/settings decide which recorded events reach your bell.
Chat notifications
/dashboard/chat has its own unread and mute state through /api/chat/<chatId>/read, /api/chat/<chatId>/mute and /api/chat/notifications. Muting a conversation stops its notifications without hiding the messages.
Debugging
- Nothing arriving: check that the SSE request is open in the network tab and that the workspace switch for that event is on.
- Arriving twice: a reconnect can replay recent rows; the feed de-duplicates by id.
- Service reachability: GET /api/health reports Postgres, realtime, storage and functions for the signed-in user.