Feature Deep-Dive: Bookmarks

What it does

Lets readers save golden nuggets and resurfaces them later via the Bookmark Shelf. It’s a lightweight loop that stores intent without cluttering the feed.

Why it matters

High-signal stories often deserve a second pass. Bookmarks give us a way to reintroduce them at calmer times without pummeling the reader with notifications.

Design

flowchart LR
User-->POST[/api/bookmarks/]-->DB[(bookmarks)]
User-->DEL[/api/bookmarks/:itemId]-->DB
User-->GET[/api/bookmarks/]-->DB
DB-->Shelf[BookmarkShelf resurfaces]

Tech choices & trade-offs

OptionPerfComplexityCostDXWhy we picked/not
Server bookmarksHighLow$GreatChosen — simple, RLS-safe
Local-onlyHighLowest$GreatNo sync/cross-device

Implementation walkthrough

Example insert:

await supabase
  .from('bookmarks')
  .insert({ user_id: user.id, item_id: parsed.data.itemId })
  .select('id')
  .single();

Smart bits (gotchas)

  • Unique constraint on (user_id, item_id) keeps toggles idempotent.
  • surfaced_at lets the Bookmark Shelf know when it last nudged a story; snoozing simply updates that timestamp.
  • We run all operations through Supabase server clients, so RLS handles security.

Testing

  • Click bookmark twice: first call inserts, second attempt should surface a constraint error handled by the client.
  • Query /api/bookmarks and confirm the latest saved story leads the array.

Operational notes

  • Consider pruning bookmarks older than six months or exporting them to cold storage if you expect heavy bookmarking.

What we’d do next

  • Add shareable bookmark lists.
  • Let users pin bookmarks to the feed header for high-priority follow-up.