feat: real-time notifications system

[davedumto]

Overview

Users currently have no way to know when they receive a tip, gain a follower, or when a creator they follow goes live. This issue covers the full notifications system from DB schema to UI.

DB schema

CREATE TYPE notification_type AS ENUM (
  'new_follower',
  'tip_received',
  'stream_live',
  'stream_ended',
  'recording_ready'
);

CREATE TABLE notifications (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID REFERENCES users(id) ON DELETE CASCADE,
  type        notification_type NOT NULL,
  title       TEXT NOT NULL,
  body        TEXT,
  metadata    JSONB,             -- e.g. { sender_username, amount, stream_title }
  read        BOOLEAN DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX notifications_user_unread ON notifications(user_id, read, created_at DESC);

API routes

Method	Route	Description
GET	/api/users/notifications	Fetch latest 50 notifications for authed user
PATCH	/api/users/notifications/:id	Mark single notification as read
PATCH	/api/users/notifications/read-all	Mark all as read
DELETE	/api/users/notifications/:id	Delete a notification

All routes require session cookie auth (existing pattern from /api/auth/session).

Where to insert notifications

Notifications should be inserted server-side whenever these events occur:

• new_follower — in POST /api/users/follow when action === "follow"
• tip_received — in Stellar webhook or after tip transaction confirm
• stream_live — in POST /api/streams/start
• recording_ready — in POST /api/webhooks/mux when type === "video.asset.ready"

Real-time delivery

Use Server-Sent Events (SSE) — simplest approach, no new infrastructure needed:

GET /api/users/notifications/stream

• Returns text/event-stream
• Polls Postgres every 5s for new unread notifications
• Sends data: {...} on new rows
• Client closes connection on unmount

Alternative: polling SWR with refreshInterval: 15000 on the notifications endpoint — acceptable for MVP.

UI

Notification bell (navbar)

• Add bell icon to top navbar with unread count badge
• Clicking opens a dropdown panel (max 5 recent, "View all" link)
• Badge disappears after opening (mark all read)

Notification panel / page

• /dashboard/notifications or a slide-out drawer
• List of notifications with:
  • Icon per type (follow → user icon, tip → coins, live → radio dot)
  • Title + body text
  • Relative timestamp (2 min ago)
  • Unread dot indicator
  • Click marks as read and navigates to relevant page

Notification settings

• app/settings/notifications/page.tsx already exists — extend it with per-type toggles:
  • New followers: on/off
  • Tips received: on/off
  • Creators going live: on/off
  • Recording ready: on/off
  • Email notifications (nodemailer already in deps)

Email notifications

• Nodemailer is already a dependency
• Send email for tip_received (creator earned money — high signal event)
• Use existing email template pattern from @react-email/render

Acceptance criteria

• notifications table created with migration script
• Notifications inserted on follow, tip, stream start, recording ready
• GET /api/users/notifications returns paginated list
• PATCH routes correctly mark as read
• Bell icon in navbar shows unread count
• Notification dropdown shows recent 5 with correct icons and timestamps
• Per-type notification preferences respected
• Email sent on tip received (if user has email notifications enabled)

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[Amarjeet325]

@Amarjeet325 has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hi, maintainers 👋.
I’d like to work on this issue.
I’m a full-stack developer and have previously contributed to multiple open-source projects.

Could you please assign this issue to me?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Amarjeet325 to this issue.

[samuelgodsgift]

@samuelgodsgift has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I have 5+ years of experience in web development. I can build a real-time notification system for your application. I would love to take on this issue! Kindly assign.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @samuelgodsgift to this issue.