Notification System Consolidation

[ntatschner]

Problem

Today's notification mechanisms are ad-hoc — roadmap subscriber updates, org events, and sharing notices each ship through their own surface, with no unified inbox, no cross-surface mute, and no consistent per-category control. As more notification-producing features land, this fragmentation compounds.

Approach

One notification path replacing the current ad-hoc surfaces.

Delivery channels (mute applies across all):

• Tray toast — always available, no opt-in
• Web inbox — opt-in, viewable in the web companion
• Discord webhook — optional, per-user URL
• Email — optional, opt-in

Per-category mute settings persist across devices via the existing two-gate sync model. All current producers (roadmap subscriber notifications, org events, sharing notifications) emit into the unified path.

Acceptance criteria

• Roadmap subscriber notifications migrate to the unified path
• Org event notifications migrate to the unified path
• Sharing notifications (share.created / share.viewed / share.reported) migrate to the unified path
• Per-category mute persists across devices
• Tray toast and web inbox share read-state
• Discord webhook URL stored encrypted via the existing KEK pattern
• Email channel is opt-in only and revocable

Risks / Open questions

• Email delivery — does StarStats hold subscriber email addresses, or route through user-provided SMTP?
• Discord webhook URLs are sensitive (anyone with the URL can post). Confirm encryption-at-rest + redaction in logs.
• Backward-compat: how do existing roadmap subscribers' implicit preferences map into per-category mute on first run?
• Notification deduplication when a user has both tray and web open simultaneously

Original draft notes

Single notification path replacing today's ad-hoc surfaces. Channels:

• Tray toast (always available)
• Web inbox (opt-in)
• Discord webhook (optional, per-user)
• Email (optional, opt-in)

Per-category mute. Used by roadmap subscriber notifications, org events, sharing notifications.

---

Tracking

• Roadmap slug: notification-system-consolidation
• Public roadmap: https://starstats.app/roadmap/notification-system-consolidation
• Project board: https://github.com/orgs/TheCodeSaiyan/projects/1
• eta_band: tbd (set on the Project board when scoping firms up)
• Channel targeting: likely live + beta + alpha — foundational platform feature touched by org events, sharing, roadmap subscribers. Add channel/<name> labels when targeting firms up.