Notifications

Real-time notification system covering comments, replies, mentions, milestones, follows, and role assignments.

Updated 11d ago

Supa Hub has a comprehensive notification system that covers all major user interactions.

Notification Types

Type	Trigger	Recipient
comment_on_post	New top-level comment on a post	Post author
reply	Reply to a comment	Parent comment author
mention	@username in a comment	Mentioned user
milestone	Post reaches a view or reaction milestone	Post author
space_role	User assigned as moderator/admin of a space	Assigned user
new_follower	Someone follows a user	Followed user
follower_post	A followed user publishes a new post	All followers

How Notifications Work

Notifications are created by database triggers, not application code. This ensures they are always generated regardless of which API endpoint or client triggers the action.

Storage

Each notification consists of two rows:

hub_notifications — The event itself (type, actor, resource, context JSON)
hub_notification_recipients — One row per recipient, with read_at tracking

The context JSONB column stores all the data needed to render the notification (post slug, space slug, post title, milestone value, etc.), so the client doesn't need additional queries.

Participant Tracking

For comment notifications, the system maintains a participation cache (hub_participation_cache). When a user comments on a post, they become a participant. All participants are notified of new comments on that post (excluding the commenter).

Real-Time Delivery

The GET /api/notifications/stream endpoint provides Server-Sent Events (SSE) for real-time notification delivery. The client keeps a persistent HTTP connection open and receives push updates as notifications arrive.

Milestones

View Milestones

Triggered when a post's view count crosses a threshold:

Predefined: 50, 100, 250, 500
Recurring: Every 1,000 views after 1,000

Reaction Milestones

Triggered when a post's total reaction count crosses a threshold:

Predefined: 5, 25, 50
Recurring: Every 100 reactions after 100

Milestones are tracked in hub_post_milestones to prevent duplicate notifications. Each (post, type, value) combination can only trigger once.

Follow Notifications

Two notification types are generated by the follow system:

new_follower — Sent to a user when someone follows them. The notification links to the follower's profile.
follower_post — Sent to all followers when a user creates a new visible post. The notification includes the post title and links directly to the post. Users who have muted a space are excluded.

Reading Notifications

GET /api/notifications — Fetch paginated notifications
GET /api/notifications/unread — Get unread count (used for badge display)
PATCH /api/notifications — Mark specific notifications as read (sets read_at)

UI Integration

The Header component displays an unread notification count badge. Clicking it opens a dropdown with an infinite-scroll list of recent notifications, each linking to the relevant post, space, or profile. Users can mark all notifications as read with a single click.

Follows

Feeds

Type

Trigger

Recipient

comment_on_post

New top-level comment on a post

Post author

Reply to a comment

Parent comment author

mention

@username in a comment

Mentioned user

milestone

Post reaches a view or reaction milestone

Post author

space_role

User assigned as moderator/admin of a space

Assigned user

new_follower

Someone follows a user

Followed user

follower_post

A followed user publishes a new post

All followers