grain.social/grain

Switch repository

Loading…

# Notifications Design

## Overview

Add a notifications system to Grain, matching grain-next's approach: computed queries over existing records (favorites, comments, follows, mentions) with read/unread tracking via server-side timestamp.

## Notification Types

1. **gallery-favorite** — someone favorited your gallery
2. **gallery-comment** — someone commented on your gallery
3. **gallery-comment-mention** — someone mentioned you in a comment
4. **gallery-mention** — someone mentioned you in a gallery description
5. **reply** — someone replied to your comment
6. **follow** — someone followed you

## Data Layer

No new database tables. Notifications are computed by querying existing records where the target matches the viewer's DID:

- `social.grain.favorite` — `subject` is a gallery URI owned by viewer
- `social.grain.comment` — `subject` is a gallery URI owned by viewer, or facets contain a mention of viewer's DID
- `social.grain.comment` (reply) — `reply_to` references a comment by viewer
- `social.grain.graph.follow` — `subject` is viewer's DID
- `social.grain.gallery` — facets in description mention viewer's DID

### Read/Unread Tracking

Store a `lastSeenNotifications` ISO timestamp in `_preferences` via the existing `putPreference` endpoint. Notifications with `created_at` after this timestamp are "unseen."

## API

### New XRPC Query: `social.grain.unspecced.getNotifications`

- **Input:** viewer DID, cursor (optional), limit (default 20)
- **Output:** paginated edges with:
  - `reason`: one of the 6 notification types
  - `author`: hydrated profile (did, handle, displayName, avatar)
  - `subject`: gallery URI or comment URI (context-dependent)
  - `gallery`: hydrated gallery info (title, thumbnail) when applicable
  - `commentText`: comment text when applicable
  - `createdAt`: timestamp
  - `cursor`: for pagination
  - `unseenCount`: count of notifications newer than `lastSeenNotifications`

The query unions results from favorites, comments, follows, and galleries, sorted by `created_at` desc.

## UI

### Bell Icon

- **Desktop:** Left sidebar, between Home and Settings icons. Shows red badge with unseen count when > 0.
- **Mobile:** Bottom bar, between Create and Profile. Same badge behavior.

### Notifications Page (`/notifications`)

- Infinite scroll list, 20 items per page
- Each row: author avatar, action text, relative timestamp, context (gallery thumbnail, comment text)
- On mount: updates `lastSeenNotifications` to now, clears badge

### Notification Row Rendering by Type

| Type                    | Action Text                  | Context                                   |
| ----------------------- | ---------------------------- | ----------------------------------------- |
| gallery-favorite        | "favorited your gallery"     | Gallery title + thumbnail                 |
| gallery-comment         | "commented on your gallery"  | Comment text + gallery thumbnail          |
| gallery-comment-mention | "mentioned you in a comment" | Comment text + gallery thumbnail          |
| gallery-mention         | "mentioned you in a gallery" | Gallery description excerpt + thumbnail   |
| reply                   | "replied to your comment"    | Reply text + original comment + thumbnail |
| follow                  | "followed you"               | (none)                                    |

## State Management

### TanStack Query Keys

- `["notifications", did]` — paginated notification list (60s stale time)
- `["unseenNotificationCount", did]` — badge count (60s stale time)

### Mark-as-Read Flow

1. User navigates to `/notifications`
2. `onMount` calls `putPreference({ key: "lastSeenNotifications", value: now })`
3. Invalidates `["unseenNotificationCount"]` — badge clears
4. Optimistic update: set count to 0 immediately

## File Changes

### New Files

- `server/xrpc/getNotifications.ts` — XRPC query handler
- `app/routes/notifications/+page.svelte` — notifications page
- `app/lib/components/atoms/NotificationItem.svelte` — notification row component

### Modified Files

- `hatk.config.ts` — register new XRPC endpoint
- `app/lib/queries.ts` — notification list + unseen count queries
- `app/lib/components/organisms/Sidebar.svelte` — bell icon with badge
- `app/lib/components/molecules/MobileBottomBar.svelte` — bell icon with badge