Favorites

Summary

A signed-in member can bookmark a patch, a collection or a campaign, and everything they've bookmarked appears on one screen at scout://favorites, grouped by kind with a filter rail. It is explicit curation only — the screen shows exactly what the user tapped a bookmark on, and nothing is inferred from what they've been doing.

Favoriting a patch and favoriting that patch's community board are the same act. A board in Scout is a patch's board, so there is one row per patch and the bookmark on the board header and the one on patch detail toggle it.

This replaced a narrower, patch-only feature: board_favorites plus a horizontal strip of favorited boards on the Community hub. Both are gone (see What this feature does NOT do).

Status

Shipped. Not behind any feature flag. No FeatureFlag/StoreFeatureFlag row governs it, and no config gates it.

Member-only. Guests — who otherwise have real backend sessions and can post, comment and import photos — cannot favorite anything. Every route is behind JwtAuthGuard (backend/src/favorites/favorites.controller.ts:14), the drawer row is gated isSignedIn rather than hasSession (mobile/src/components/navigation/drawerSections.ts), and tapping a bookmark as a guest raises the sign-in prompt without firing a request (mobile/src/components/favorites/FavoriteButton.tsx:46).

User-facing surfaces

• Favorites screen — mobile/app/(drawer)/favorites.tsx → FavoritesScreen (mobile/src/screens/FavoritesScreen.tsx), deep link scout://favorites, drawer row Favorites in the COLLECTION section (between Community and Import). Registered in mobile/src/dev/deepLinkRoutes.ts. Its chrome is My Patches' top bar (since 2026-10-29): a glass back button and the title Favorites, nothing on the right. There is no hamburger on this screen — the back control (favorites-back) is the only top chrome, so the drawer is not reachable from here; it falls back to / when there is no stack to pop, which is the cold scout://favorites case.
• Bookmark on patch detail — in the hero's top-right chrome, beside the vouch heart (mobile/src/components/patch-detail-v2/HeroSwiper.tsx, testID patch-hero-favorite). Renders as the design system's IconButton, clear glass when off and accent-tinted glass (a filled bookmark) when on — Liquid Glass on iOS 26+.
• Bookmark on a patch's community board — floating over the board's photo banner, opposite the back button (mobile/src/screens/PatchCommunityScreen.tsx, behind the route mobile/app/patch-community/[id].tsx; testID community-favorite). The same chrome IconButton as the patch hero's, clear glass off and accent-tinted glass on. Same favorite as the patch's.
• Bookmark on campaign detail — mobile/app/campaign/[id].tsx, testID campaign-favorite, mirroring the back button on the opposite edge.
• Bookmark on a collection — a collection in a campaign opens The Ring, mobile/src/components/campaign/CampaignRingScreen.tsx:322, testID campaign-ring-favorite. One with no campaign keeps mobile/src/components/campaign/CampaignCollectionScreen.tsx, testID campaign-collection-favorite.

What the screen shows

"The shelf" — on develop since 2026-10-29, not released (design: mobile/research/favorites-redesign-lab.html take A, picked by Alan; it replaced favorites-approved.html's Near Me-style list rows). Top to bottom:

• The count — My Patches' header, shared as CountHeader (mobile/src/components/count-header): kicker Saved, the number big in brass (favorites-count), and the facts "N patches · N collections · N campaigns". It counts every favorite, whatever the filter.
• The chips — All N, then one per kind with its count (FilterPill, favorites-filter-<all|patch|collection|campaign>). A chip narrows the shelf to one kind; a kind with zero favorites keeps its chip, dimmed, so the row does not reflow under the thumb. There is no separate filter button: the kinds are the only facet.
• Working on (favorites-section-working) — the saved collections, then the saved campaigns (the old fixed order), newest first within each, as a horizontal rail of the Album's photo cover cards (CoverCard, 168 × 210): the photo (a collection's first member patch with a place photograph, else its icon; a campaign's hero), the kicker (the collection's category, or "Campaign"), the name, "got of total", and the gold progress line. Card testID favorite-row-<id>.
• Patches (favorites-section-patch) — the saved patches, newest first, on the shared patch grid (PatchGrid, the one My Patches and the ring boards draw; tile fav-patch-<id>), with the heading "k of n collected". Each tile's pill is "Collected" when you have it, otherwise the distance from where you are (formatDistance; no pill without a location fix).
• Removing — a small bookmark on each card's and tile's top-right corner (FavoriteButton on a dark glass dot, favorite-remove-<id>, reading "Remove from favorites"). It sits outside the card's or tile's press, so removing never also opens the thing being removed (PatchGrid gained a corner slot for this).
• Tapping opens /patch-modal/<id>, /campaign-collection/<id> or /campaign/<id>.
• States — loading (a skeleton in the shelf's shape: header, two cards, a grid), error (with Try again), nothing saved (three faded catalogue patches, "Nothing saved yet", Find something nearby → Near Me; no count, no chips), and a filter that matches nothing ("No collections saved … still under All").

The pure favoritesShelf (mobile/src/screens/favoritesShelf.ts) decides what the shelf holds: the order, the filter, each patch's distance and collected flag, and the counts.

How it works

1. Toggle. FavoriteButton calls useFavorites().toggle(kind, entityId). was is read from the TanStack cache, not the rendered list, so two taps in one frame don't both act on the same stale decision (mobile/src/hooks/useFavorites.ts).
2. Optimistic write. favoriteToggleMutation (mobile/src/query/queries/favorites.ts) cancels in-flight list queries, snapshots the cache, writes optimistically, rolls back in onError and invalidates in onSettled. Rows are matched on kind AND entityId, never id alone.
3. Request. POST or DELETE /api/favorites/:kind/:entityId.
4. Server. FavoritesService validates the kind, checks the entity exists, then upserts on the (user, target) unique index — so favoriting twice is one row. Removal is a deleteMany, so unfavoriting something already gone is a no-op.
5. Read. GET /api/favorites returns a newest-first list of { kind, entityId, createdAt, postCount? } — ids only.
6. Resolution on-device. FavoritesScreen joins those ids against the content already cached from GET /api/sync/content, and recomputes collection and campaign progress locally via deriveCollectionsWithProgress / deriveCampaignsWithProgress — the same client-side derivation the rest of the app uses. Nothing about progress is stored or sent.

Why the API returns ids

The app already caches every patch, collection and campaign under one query key. Hydrating favorites server-side would ship a second, staler copy of content the client already holds. postCount is the single exception — post counts are not in the sync payload, so patch rows carry one.

Data model

UserFavorite → user_favorites (backend/prisma/schema.prisma):

• id (uuid), userId, kind ('patch' | 'collection' | 'campaign'), createdAt
• patchId? / collectionId? / campaignId? — real FKs to patches, collections, campaigns, all onDelete: Cascade
• @@unique([userId, patchId]), @@unique([userId, collectionId]), @@unique([userId, campaignId]) — Postgres allows unlimited NULLs in a unique index, so each constrains only rows of its own kind
• @@index([userId, createdAt(sort: Desc)]) — drives the list query
• user_favorites_one_target CHECK (migration only; Prisma cannot express it): exactly one FK is set and kind names that same column

Three FKs rather than a polymorphic (entity_type, entity_id) pair because patches and collections are genuinely deleted through the content-publish flow. Without the cascade, a favorite would survive as a dangling id and render as a card with no name; the alternative is a scheduled sweep that has to know every entity type.

user_favorites is user data, not publishable content, so it is deliberately absent from backend/src/content-publish/content-entities.ts — same as user_patches.

API surface

All JwtAuthGuard, all in backend/src/favorites/favorites.controller.ts:

Registered in backend/api-tests/route-registry.ts and driven by an api test.

Key files

Backend:

• backend/prisma/schema.prisma — UserFavorite, and the favorites back-relations on Patch, Collection, Campaign.
• backend/prisma/migrations/20260902120000_user_favorites/migration.sql — creates the table, copies board_favorites forward, drops it.
• backend/src/favorites/favorites.service.ts — all data access; COLUMN maps kind → FK column and must agree with the CHECK constraint.
• backend/src/favorites/favorites.controller.ts, favorites.module.ts, dto/index.ts.
• backend/src/achievements/feature-context.ts — the board_favorited achievement metric now counts patch favorites.

Mobile:

• mobile/src/api/favorites.ts — favoritesApi, Favorite, FavoriteKind.
• mobile/src/query/queries/favorites.ts — query + optimistic toggle.
• mobile/src/hooks/useFavorites.ts — the one hook.
• mobile/src/components/favorites/FavoriteButton.tsx — the one toggle, bare and chrome variants.
• mobile/src/screens/favoritesShelf.ts — the pure shelf (order, filter, distance, collected, counts).
• mobile/src/components/count-header/CountHeader.tsx — the header, shared with My Patches. mobile/src/components/patch-grid/PatchGrid.tsx — the grid (its corner slot carries the remove bookmark). mobile/src/components/album/places/CoverCard.tsx — the Working on cards.
• mobile/src/screens/FavoritesScreen.tsx — the shelf, the chips, all states. Split into a view model and a layout in one file: FavoritesScreenViewModelImpl() owns every hook, the id→content resolution, the filter state and the navigation actions and returns a FavoritesScreenViewModel; FavoritesScreenLayout({ viewModel }) is pure UI and touches no hook, so it renders correctly from a hand-built object. FavoritesScreen is the two-line composition of the pair, and is still what the route renders. Filtering and ordering happen in favoritesShelf, which the view model calls; the layout never derives what belongs where.
• mobile/src/dev/mocks/favorites.tsx — the screen's seven DEV mock states (scout://dev-screen-mock/favorites/<state>), which exist because of the view model split above. See screen-mocks.
• mobile/src/components/ui/FilterPill.tsx — FilterPill + FilterPillRail, the gold-fill pill rail shared with the Achievements screen. The screen owns the pills' labels, counts and dim rule; the component owns how they look and the rail's layout.
• mobile/research/favorites-redesign-lab.html — the shelf (take A, picked 2026-10-29) and the two takes it was chosen over; favorites-approved.html and favorites-lab.html — the previous design (2026-09-02) and its variants.

Configuration and flags

None. No feature flag, no app-config value, no environment variable.

Edge cases and known limits

• Guest taps a bookmark — sign-in prompt, no request fired.
• Failed toggle (offline, 500) — the optimistic write rolls back and the list query is invalidated, so the server stays authoritative. The user retries; the change is not queued.
• Favorited entity deleted server-side — Postgres cascades the row away; the next GET /api/favorites simply omits it.
• Favorited entity missing from the device's sync cache — the row is skipped, not rendered as a nameless card. Reachable in normal use: adminOnly collections are stripped from the sync payload, and a stale cache lags a content publish. A consequence is that such a favorite is invisible on the screen while still existing server-side, and the header count reflects only what resolved.
• Filter matching nothing — its own state ("No collections saved"), distinct from the screen-level empty state.
• No favorites at all — the chips and the count are hidden entirely, not rendered with zeroes.
• No location fix — saved patches show no distance pill (the collected ones still say "Collected").
• A patch and a collection sharing an id — handled: every lookup and every cache mutation matches on kind and id.

What this feature does NOT do

• It does NOT surface "continue where you left off". Nothing is auto-added, auto-ranked, or inferred from progress, recency or location. A campaign the user is halfway through does not appear here unless they bookmarked it. This was considered and explicitly rejected.
• It does NOT let you reorder, pin to top, tag, annotate, or foldering favorites. Sort is newest-first within a fixed section order, full stop.
• It does NOT sort or filter by where you are, and offers no navigate action. A saved patch shows its distance (since 2026-10-29) only as a pill; the order is still newest first, and nothing here routes you there.
• It does NOT work for guests. A guest cannot favorite anything and the drawer row is hidden from them, even though guests hold real sessions elsewhere in the app.
• It does NOT sync offline writes. A toggle made with no connection is rolled back, not queued for replay.
• It does NOT appear on the Home screen, or anywhere else. The drawer row and scout://favorites are the only entry points.
• There is NO separate "favorite board". The Community hub's horizontal strip of favorited boards is deleted, and so is the board_favorites table. Favoriting a patch is what following its board now means.
• It does NOT share, publish or expose favorites to anyone else. There is no public favorites list, no friend view, no count shown to other users.
• It does NOT notify. Favoriting produces no notification for anyone, and new activity on a favorited board does not notify the user who favorited it.
• It does NOT affect unlock, progress, achievements or the store. The one achievement metric that touches it — board_favorited — counts patch favorites, exactly as it counted board favorites before.

Tests that cover it

• backend/src/favorites/favorites.service.spec.ts — 12 unit tests: unknown kind 400s before touching the DB, unknown entity 404s, upsert idempotency, per-kind column writes, cross-kind delete isolation, no-op delete, newest-first ordering, postCount presence and zero, and no groupBy when nothing patch-shaped is favorited.
• backend/src/favorites/favorites.db.spec.ts — real Postgres: the cascade actually fires, the CHECK rejects a two-target row and a mismatched kind, and the unique indexes coexist across many NULLs. Running in the db tier also proves the hand-written migration applies to a clean database.
• backend/api-tests/favorites.api.spec.ts — all three routes through the real guard chain, both branches: 401 for anonymous, and a full round-trip proving a POSTed favorite comes back from GET and disappears on DELETE.
• mobile/src/components/ui/__tests__/FilterPill.test.tsx — the pill's selected/unselected/dim opposites, and the rail's layout contract. The layout assertions are a regression guard: the rail was a bare <ScrollView horizontal>, whose flexGrow: 1 (React Native's own baseHorizontal) made it split the viewport with the list and stretched every pill into a screen-height capsule.
• mobile/src/query/__tests__/favoritesQueries.test.ts — optimistic add/remove, rollback on failure, cross-kind isolation, and the request actually sent.
• mobile/screen-tests/favorites.test.tsx — the shelf (count, facts, Working on cards with the category kicker and "0 of 4", the grid tile with its distance) and the empty state as paired opposites; "Collected" vs a distance vs no fix; a card opens while the corner bookmark removes without opening; the skip-missing-entity rule; the error state; waiting for content; and the chip pair (a kind with rows vs one without). Written against the old screen first (6 of 10 failed), then green on the shelf.
• mobile/src/screens/__tests__/favoritesShelf.test.ts — order, distance, no-fix, the filter and counts, progress. mobile/screen-tests/patch-grid.test.tsx — the corner slot sits outside the tile's press.
• mobile/screen-tests/community.test.tsx — regression: a signed-in member sees no favorites strip and the screen issues no favorites request.
• mobile/maestro/tests/favorites.yaml — the E2E, on a production-simulator build against prod. Empty state (rail and count absent, no hamburger) → bookmark a patch from the detail hero, a campaign, and a collection, each from its own screen → all three resolve as named rows under their sections → the chips narrow the shelf to one kind → the patch's community board already reads selected: true, which is the one-favorite-per-patch claim proven across two surfaces → clearing it there removes the row → the empty FILTER state → unfavourite from the cards' corners down to the screen-level empty state again. Updated for the shelf 2026-10-29; not yet run against it. Entities are named (san-francisco-golden-gate-bridge, san-francisco, route-66), never globbed: a globbed row would pass without the id → sync-cache join that GET /api/favorites returning ids only makes load-bearing. The guest branch is deliberately absent — the suite may never enter as a guest.
• Drift: mobile/src/dev/__tests__/deepLinkRoutes.test.ts, screenTestRegistry.test.ts, drawerSections.test.ts (icon collision + the COLLECTION section's order and the row's isSignedIn gate).

Open questions

• The migration's copy-forward has not been exercised against production data. It was verified against the worktree clone (one row) and against a clean fixture database (zero rows). How many board_favorites rows exist in prod is unknown from here — the prod database was deliberately not queried.
• Scroll behaviour and the hero chrome over real imagery are still only eyeballed. The Maestro flow (below) verified the screen end to end on a production simulator build on 2026-09-02, so the states and the toggles are no longer unverified — but nothing asserts how a long list scrolls, and the bookmark's contrast over an arbitrary hero photograph is a judgement call no test makes.