Notifications Overview
Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
Notifications Studio turns raw platform events into concise, tenant-scoped alerts that reach the right responders without overwhelming them. The service is sovereign/offline-first, follows the Aggregation-Only Contract (AOC), and produces deterministic outputs so the same configuration yields identical deliveries across environments.
1. Mission & value
- Reduce noise. Only materially new or high-impact changes reach chat, email, or webhooks thanks to rule filters, throttles, and digest windows.
- Explainable results. Every delivery is traceable back to a rule, action, and event payload stored in the delivery ledger; operators can audit what fired and why.
- Safe by default. Secrets remain in external stores, templates are sandboxed, quiet hours and throttles prevent storms, and idempotency guarantees protect downstream systems.
- Offline-aligned. All configuration, templates, and plug-ins ship with Offline Kits; no external SaaS is required to send notifications.
2. Core capabilities
| Capability | What it does | Key docs |
|---|---|---|
| Rules engine | Declarative matchers for event kinds, severities, namespaces, VEX context, KEV flags, and more. | notifications/rules.md |
| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | notifications/architecture.md |
| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides, including the attestation lifecycle suite (tmpl-attest-*). | notifications/templates.md |
| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | notifications/digests.md |
| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | modules/notify/architecture.md |
| Ack tokens | DSSE-signed acknowledgement tokens with webhook allowlists and escalation guardrails enforced by Authority. | modules/notify/architecture.md |
3. How it fits into Stella Ops
- Producers emit events. Scanner, Scheduler, VEX Lens, Attestor, and Zastava publish canonical envelopes (
NotifyEvent) onto the internal bus. - Notify.Worker evaluates rules. For each tenant, the worker applies match filters, VEX gates, throttles, and digest policies before rendering the action.
- Connectors deliver. Channel plug-ins send the rendered payload to Slack/Teams/Email/Webhook targets and report back attempts and outcomes.
- Consumers investigate. Operators pivot from message links into Console dashboards, SBOM views, or policy overlays with correlation IDs preserved.
The Notify WebService fronts worker state with REST APIs used by the UI and CLI. Tenants authenticate via StellaOps Authority scopes notify.viewer, notify.operator, and (for escalated actions) notify.admin. All operations require the tenant header (X-StellaOps-Tenant) to preserve sovereignty boundaries.
4. Operating model
| Area | Guidance |
|---|---|
| Tenancy | Each rule, channel, template, and delivery belongs to exactly one tenant. Cross-tenant sharing is intentionally unsupported. |
| Determinism | Configuration persistence normalises strings and sorts collections. Template rendering produces identical bodyHash values when inputs match; attestation events always reference the canonical tmpl-attest-* keys documented in the template guide. |
| Scaling | Workers scale horizontally; per-tenant rule snapshots are cached and refreshed from Mongo change streams. Redis (or equivalent) guards throttles and locks. |
| Offline | Offline Kits include plug-ins, default templates, and seed rules. Operators can edit YAML/JSON manifests before air-gapped deployment. |
| Security | Channel secrets use indirection (secretRef), Authority-protected OAuth clients secure API access, and delivery payloads are redacted before storage where required. |
| Module boundaries | 2025-11-02 decision: keep src/Notify/ as the shared notification toolkit and src/Notifier/ as the Notifications Studio runtime host until a packaging RFC covers the implications of merging. |
5. Getting started (first 30 minutes)
| Step | Goal | Reference |
|---|---|---|
| 1 | Deploy Notify WebService + Worker with Mongo and Redis | modules/notify/architecture.md |
| 2 | Register OAuth clients/scopes in Authority | etc/authority.yaml.sample |
| 3 | Install channel plug-ins and capture secret references | plugins/notify |
| 4 | Create a tenant rule and test preview | POST /channels/{id}/test |
| 5 | Inspect deliveries and digests | /api/v1/notify/deliveries, /api/v1/notify/digests |
6. Alignment with implementation work
| Backlog item | Impact on docs | Status |
|---|---|---|
NOTIFY-SVC-38-001..004 | Foundational correlation, throttling, simulation hooks. | In progress – align behaviour once services publish beta APIs. |
NOTIFY-SVC-39-001..004 | Adds correlation engine, digest generator, simulation API, quiet hours. | Pending – revisit rule/digest sections when these tasks merge. |
Action: coordinate with the Notifications Service Guild when NOTIFY-SVC-39-001..004 land to validate payload fields, quiet-hours semantics, and any new connector metadata that should be documented here and in the channel-specific guides.
Imposed rule reminder: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.