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
| Option | Perf | Complexity | Cost | DX | Why we picked/not |
|---|---|---|---|---|---|
| Server bookmarks | High | Low | $ | Great | Chosen — simple, RLS-safe |
| Local-only | High | Lowest | $ | Great | No sync/cross-device |
Implementation walkthrough
- GET/POST live in
web/src/app/api/bookmarks/route.ts. - Delete sits in
web/src/app/api/bookmarks/[itemId]/route.ts. bookmarkstable schema mirrors the API:user_id,item_id,bookmarked_at, plussurfaced_atto avoid repeat resurfacing.
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_atlets 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/bookmarksand 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.