notifications

Notifications + SSE

In-app notifications persist as rows in the notifications table and stream to the user's personal channel in realtime via SSE. Facteur (@facteurjs/adonisjs) is the framework: one Notification<User, Params> class per type, with a deliverBy: { database, transmit } config and per-channel methods (asDatabaseMessage, asTransmitMessage). Transmit (@adonisjs/transmit) is the SSE transport — in-memory / single-node by default (transport: null in config/transmit.ts); swap to a distributed transport (e.g. Redis) when scaling out to multiple instances. Emission always goes through domain events: actions emit, a listener calls facteur.notification(...).params(...).to([user]).send().

Rules

• A dedicated notifications module owns the model, transformer, controller and routes for the bell:
  • GET /notifications → list + unseen count.
  • POST /notifications/:id/read → mark one read.
  • POST /notifications/seen → mark all as seen (the dot disappears; row stays "unread").
  • POST /notifications/read → mark all read.
• Notification classes live at app/<mod>/notifications/<name>_notification.ts, extending Notification<User, Params>:

  static options = { name: 'user-welcome', deliverBy: { database: true, transmit: true } }
  asDatabaseMessage() { return DatabaseMessage.create().setType(...).setContent({...}).setTags([...]) }
  asTransmitMessage() { return TransmitMessage.create().setContent({ kind: '...' }) }
  

• User routing via User.notificationTargets():

  {
    database: { notifiableId: String(this.id) },
    transmit: { channel: `notifications/user-${this.id}` },
  }
  

  Facteur maps each channel's target automatically.
• Emission goes through events — see [[actions-events]]. The listener calls:

  await facteur.notification(SomeNotification).params({...}).to([user]).send()
  

• Shared prop unseenNotifications (count) is computed in the Inertia middleware when a user is authenticated. It powers the bell badge on first render — the SSE stream keeps it in sync afterward.
• Bell UI subscribes to the per-user channel via useNotificationsChannel(user.id, onIncoming), hits the endpoint to fetch the list when opened, marks-all-seen on open, marks-read on click.
• Frontend SSE client is a lazy singleton: one EventSource on /__transmit/events, all channels multiplex through it.
• SSE transport — apps/web/config/transmit.ts defaults to transport: null (in-memory, single-node). The @adonisjs/transmit provider auto-registers the /__transmit/* routes, so the bell works out of the box. Swap transport for a distributed driver (Redis) when horizontally scaling.