git.stella-ops.org/docs/modules/notify

StellaOps Notify

Notify (Notifications Studio) converts platform events into tenant-scoped alerts with deterministic delivery, offline parity, and a full audit trail. The service is split between the reusable tooling in src/Notify/* and the runtime host in src/Notifier/* (decision recorded 2025-11-02) so downstream systems can embed the rules engine without inheriting the Studio UI.

Scope & responsibilities

• Apply tenant-scoped rules to events from Scanner, Scheduler, VEX Lens, Attestor, Task Runner, and Zastava.
• Render channel-specific payloads (Slack, Teams, Email, webhook) using deterministic templates with localisation safeguards.
• Enforce throttling, digests, and quiet-hour calendars so bursts stay explainable and recoverable.
• Persist deliveries, attempts, throttles, and DSSE hashes for CLI/UI investigation and compliance export.

Current capabilities (Sprint 38 foundations)

• Rules + channels API: StellaOps.Notify.WebService exposes CRUD, previews, and health probes secured by Authority scopes.
• Worker pipeline: StellaOps.Notify.Worker ingests bus events, evaluates match predicates, applies per-tenant throttles, and dispatches deliveries.
• Connector plug-ins: Restart-time plug-ins under StellaOps.Notify.Connectors.* (Slack, Teams, Email, generic webhook) with health checks and retry policy hints declared in notify-plugin.json.
• Template engine: Deterministic rendering with safe helpers, locale bundles, and redaction defaults that keep Offline Kit parity.
• Delivery ledger: Mongo-backed ledger storing hashed payloads, attempts, throttled/digested markers, and provenance links for audit + exports.

In progress / upcoming (Sprint 39 focus)

• NOTIFY-SVC-39-001 correlation engine with token-bucket throttles, incident lifecycle, and quiet-hours evaluator.
• NOTIFY-SVC-39-002 digest generator with schedule runner, ledger queries, and distribution across existing channels.
• NOTIFY-SVC-39-003 simulation API for rule dry-runs against historical events.
• NOTIFY-SVC-39-004 quiet-hour calendar integration and default throttles with audit logging. Status for these items is tracked in src/Notifier/StellaOps.Notifier/TASKS.md and sprint plans; update this README once tasks merge.

Key docs & release alignment

• docs/notifications/overview.md — summary of capabilities, imposed rules, and customer journey.
• docs/notifications/architecture.md — Notifications Studio runtime view (published 2025-10-29).
• docs/notifications/rules.md — declarative matcher syntax and evaluation order.
• docs/notifications/digests.md — digest windows, coalescing logic, and delivery samples.
• docs/notifications/templates.md — template helpers, localisation, and redaction guidelines.
• docs/updates/2025-10-29-notify-docs.md — latest release note; follow-ups remain to validate connector metadata, quiet-hours semantics, and simulation payloads once Sprint 39 drops land.

Integrations & dependencies

• Storage: MongoDB (rules, channels, deliveries, digests, throttles) with change streams for worker snapshots.
• Queues: Redis Streams or NATS JetStream for ingestion, throttling, and DLQs (notify.dlq).
• Authority: OpTok-protected APIs, DPoP-backed CLI/UI scopes (notify.viewer, notify.operator, notify.admin), and secret references for channel credentials.
• Observability: Prometheus metrics (notify.sent_total, notify.failed_total, notify.digest_coalesced_total, etc.), OTEL traces, and dashboards documented in docs/notifications/architecture.md#12-observability-prometheus--otel.

Operational notes

• Schema fixtures live in ./resources/schemas; event and delivery samples live in ./resources/samples for contract tests and UI mocks.
• Offline Kit bundles ship plug-ins, default templates, and seed rules; update manifests under ops/offline-kit/ when connectors change.
• Dashboards and alert references depend on DEVOPS-NOTIFY-39-002; coordinate before renaming metrics or labels.
• When releasing new rule or connector features, mirror guidance into docs/notifications/*.md and checklists in docs/updates/2025-10-29-notify-docs.md until the follow-ups are closed.

Epic alignment

• Epic 11 – Notifications Studio: notifications workspace, preview tooling, immutable delivery ledger, throttling/digest controls, and forthcoming correlation/simulation features.