MCM-13 — Notification System
Overview, personas, and architecture for the MCM platform notification system.
MCM-13 — Notification System
The MCM platform generates events continuously — budget thresholds breached, deployments finishing, policy violations detected, approval requests pending. The Notification System surfaces these events to the right users at the right time through three delivery channels: real-time WebSocket in-app notifications, browser-level Web Push for out-of-focus alerts, and Email for persistent, actionable records.
Each user story below is a self-contained page with its own acceptance criteria, technical design, and UI changes. This page holds only what's shared across all of them: personas, the shared delivery-channel architecture, notification taxonomy, and cross-cutting NFRs.
Personas
| Persona | Role | Primary concern |
|---|---|---|
| Enterprise Admin | Manages accounts, users, and policies within a tenant | Operational health of the entire enterprise |
| FinOps User | Monitors cost, budgets, and forecasts | Cost anomalies, budget breaches |
| SecOps User | Manages governance policies and security scans | Policy violations, critical CVEs |
| Orchestration User | Deploys and manages workspaces and stacks | Deployment outcomes, approval gates |
| MSP Admin | Manages multiple enterprise tenants | Tenant-level health events |
User Stories
| Story | Summary |
|---|---|
| MCM-14 — Real-Time In-App Notification Bell | A notification bell in the top nav shows unread alerts in real time. |
| MCM-15 — WebSocket Real-Time Delivery | The transport that pushes events to the bell within 2 seconds. |
| MCM-16 — Web Push Notification | Browser-level push alerts even when the MCM tab isn't focused. |
| MCM-17 — Email Notification | Persistent, actionable email record for critical events. |
| MCM-18 — Notification Preferences | Per-category, per-channel opt-in/opt-out control. |
| MCM-19 — MSP-Level Notifications | A separate feed for MSP Admins covering tenant-level events. |
| MCM-45 — Module Usage Plan Threshold and Expiry Notifications | Warn when a module's own usage plan nears or hits its limit, independent of the enterprise's overall subscription. |
| MCM-46 — FinOps New Recommendation Notification | Notify when a new cost-saving recommendation is generated, with a "new" indicator that outlives the notification itself. |
System Context — Delivery Channel Summary
Channel Characteristics
| Channel | Latency | Requires login | Persisted | User opt-out |
|---|---|---|---|---|
| WebSocket (In-App) | < 2 s | Yes | Yes (server-side history) | Per category |
| Web Push | 2–10 s | No (browser running) | No (fire-and-forget) | Per category + browser |
| < 60 s | No | Yes (email thread) | Per category + unsubscribe link |
Notification Categories
| Category | Examples | Default severity |
|---|---|---|
| Budget & Cost | Budget threshold breached (50 %, 80 %, 100 %), cost anomaly detected, FinOps job failure | High |
| Recommendations | New FinOps cost-saving recommendation generated (see MCM-46) | Medium |
| Discovery | Account sync completed, account sync failed at account level, job status/progress, new resource type discovered | Medium / High (account-level failure) |
| Governance | Policy violation detected, compliance score change ≥ 10 %, compliance score below 90 % on a scan run | High |
| SecOps | Critical CVE found, new security finding, scan failed, scan completed | High / Medium |
| Orchestration | Workspace plan succeeded/failed, provision (apply) succeeded/failed, deprovision (destroy) succeeded/failed, approval request received, approval approved/rejected | High / Medium |
| Module Usage Plans | A module's own usage plan (Discovery, FinOps, SecOps, Governance, or Orchestration) reaches 90 % (warning) or 100 % (expired) — see MCM-45 | Medium / High |
| Billing | Invoice generated, payment failed, subscription expiry warning | High |
| User Management | New user added, user activated, user deactivated, user role changed, password changed | Low |
| System | Platform maintenance window, service degradation, scheduled job failure | High / Low |
Enterprise-account-level activation/deactivation (as distinct from an individual user's) is a tenant-level event surfaced to MSP Admins — see MCM-19 — MSP-Level Notifications, not this table.
Notification Severity Levels
| Level | Meaning | Badge colour |
|---|---|---|
| Critical | Immediate action required — data loss, security breach, payment failure | Red |
| High | Prompt attention needed — budget exceeded, deployment failed, policy violation | Orange |
| Medium | Awareness required — sync completed with warnings, score change | Yellow |
| Low | Informational — user added, scan completed successfully | Grey |
Cross-Cutting Non-Functional Requirements
These apply across every delivery channel; channel-specific NFRs are called out on that channel's own story page.
| ID | Requirement |
|---|---|
| NFR-01 | No notification must be delivered to a user who does not belong to the tenant that owns the triggering resource (strict tenant isolation). |
| NFR-02 | All notification payloads in transit must be encrypted (TLS 1.2+). |
| NFR-03 | Notification history is retained for 7 days; anything older is not returned by the bell drawer or its API, regardless of channel. |
Out of Scope
- SMS / WhatsApp delivery channels (future consideration).
- In-app notification sounds.
- Notification grouping / threading (batching multiple events into a single notification entry).
- Third-party webhook delivery (e.g. Slack, PagerDuty) — tracked separately.
MCM-41 — Invite a Teammate to the Organization
An Org Owner invites a specific teammate by email, creating their account directly instead of waiting for them to sign up and request to join.
MCM-14 — Real-Time In-App Notification Bell
A notification bell in the top navigation bar shows unread alerts in real time.