Skip to content
emergent engineering

Notifications and messaging system

Status: proposed (2026-06-17) — stub; not yet designed. Needs its own grilling session.

Context

Section titled “Context”

Spun out of the Discussion-capability design session (ADR-0029). Several current and planned features need to tell a Person something happened, but emergent has no notification or messaging system today. Rather than grow a discussion-specific notifier, this records the block as cross-cutting, to be designed on its own merits.

Known consumers (the forcing contexts):

  • Discussion subscriptions (v2) — “someone replied to your Post / posted in your Group / in a Discussion you follow.” The immediate trigger: ADR-0029 ships only a local last-seen “new posts” badge and defers all subscription/notification machinery here.
  • Assessment due-date reminders — assessment_definition.dueAt / assignAt exist with no reminder path.
  • Grade-posted — a gradebook_entry reaching graded (especially human-scored assignments, ADR-0027).
  • Moderation / safety alerts — a Report filed → notify moderators; a Post hidden or a posting restriction imposed → notify the affected Person (ADR-0029 moderation surface).
  • Identity / invite delivery — Claim Tokens / invites (identity-linking).
  • A future real-time Chat surface (ADR-0029 deferred seam B) would also consume it.

Questions to grill (not yet decided)

Section titled “Questions to grill (not yet decided)”
  • Channels: in-app only? email? web/native push? Which at v1?
  • Subscription model: what is subscribable, opt-in vs opt-out defaults, per-Discussion “follow”.
  • Per-person state & sync: do notifications ride the pgxsinkit rail owner-scoped (like Reports and the unread marker in ADR-0029) so they work offline, or are they server-pushed online-only? Likely hybrid.
  • Preferences: immediate vs digest, quiet hours, per-channel / per-type toggles.
  • Minors & consent: emailing/pushing to minors carries guardian-consent implications (ADR-0008); channel availability may be governed, not just preferenced.
  • Delivery infra: email (provider/SMTP) and push (VAPID/web-push, native) are new k3s/Helm infrastructure with their own secrets and deploy weight.
  • Erasure: notification rows are person-PII → an erasure class; pending deliveries to an erased Person must be cancelled.
  • Neutral vocabulary: “Notification” vs “Message” vs “Alert” — settle against CONTEXT.md when designed.

Status note

Section titled “Status note”

This ADR is a placeholder so the block is not forgotten: it records that the decision is owed and what must be weighed, not a decision. Do not implement against it until it is grilled and moves to accepted. Tracked in TODO.md → Notifications & messaging.