Turn platform events into delivered notifications across five channels and one live SSE stream, every inbox scoped per user and every fan-out bounded by tenant and host allowlist.
A finding changes status, an SLA breaches, a scan finishes, a report is ready. The Notification domain is PMAP fan-out delivery engine: it receives events from the platform event bus and routes them to up to five channels. The Realtime domain is the push backbone, a single Server-Sent Events stream that updates connected browsers without polling.
Notification is a leaf domain. It consumes events that finding, scan, report, and the approval workflow emit, then delivers them, and it drives no other domain in turn. Every inbox row is scoped to a single user, so each person sees only their own notifications and no cross-tenant delivery is possible.
The hard problem is not sending a message. It is delivering the right event to the right person on the channel they chose, without leaking across tenants and without a slow recipient stalling everyone else.
At a glance
- Channels: In-app bell, email (SMTP), webhook, Slack, and Microsoft Teams
- In-app inbox: Per-user, cursor-paginated, filterable by read state and event type
- Real-time push: Single SSE stream at GET /api/v1/events; no WebSocket, no message broker
- Admin rules: Per event type, per channel, severity-filtered; unique on (event, channel, severity)
- Preferences: Per-user matrix of event by channel; namespaced and legacy keys supported
- Scope: Inbox scoped to user_id; SSE scoped to companies the client may access
- Safety: Teams and personal-chat URLs host-allowlisted; delivery failures swallowed and logged
How it works
One event bus fans out to five channels and one live stream, each delivery scoped to the recipients it concerns and the tenant they may access, so the right person sees the right event without polling and without cross-tenant leakage.
When a domain emits an event, HandleEvent runs in a background goroutine so the originating request is never blocked. It resolves recipients, consults preferences and admin rules, and fans the event out to each channel that should fire. A delivery that fails is logged and swallowed, never returned to the finding or scan flow that triggered it.
The SSE stream gives every browser tab sub-second updates without polling. A connection authenticates, resolves the companies it may access, and then receives only events scoped to those companies. The per-user preference matrix decides which channels fire for each event, and a buffered channel keeps one slow client from stalling the hub.
Key capabilities
- Per-user preference matrix. Each user opts in or out of specific event by channel combinations stored as JSONB on the profile. Dispatch consults WantsChannelForEvent before any personal address or chat URL is used, and both namespaced keys and legacy keys resolve correctly, so an existing choice is honored.
- Admin rule engine. Platform admins define per-event-type, per-channel, severity-filtered rules that decide which channels activate and supply static email recipients or webhook URLs. A unique constraint on event, channel, and severity blocks duplicates, returning a 409 rather than firing twice.
- Approval fan-out. The approval workflow has dedicated routing. A new request notifies every approver candidate, while approved, rejected, cancelled, and expired outcomes notify only the original requester, so each party hears exactly the decision that concerns them and nothing more.
- Back-pressure handling. Each SSE connection has a buffered channel of 128 frames. If a consumer falls behind and the buffer fills, the frame is dropped and logged with a non-blocking send, so a single laggy client can never stall event publication for the other connections on the hub.
Use cases
- Catch an SLA breach in the moment. A finding crosses its SLA deadline. The sla_breached event fans out to an in-app row for the assignee, an email if a matching rule is enabled, and a live SSE frame that flips the notification bell badge without the analyst reloading the page.
- Route criticals to a team channel. A platform admin creates a webhook rule for finding_created filtered to high severity. New critical findings post to the configured endpoint, while info and low findings are suppressed for that rule, so the channel carries signal rather than noise.
- Notify the right approvers. An analyst submits a finding for approval. The approval_requested event notifies every approver candidate, and once one approves, only the original requester is told the outcome, so each party hears exactly the decision that concerns them.
One event bus, five channels, one live stream, scoped to the right people.
