Wishlists & Collections — Architecture Guide

The Wishlists & Collections system enables Visitors and Buyers to save Products, Services, and Malets into named, user-defined lists with per-item quantities and notes. It uses a dual-persistence architecture: local-first (localStorage + IndexedDB) for instant UI, with background GraphQL sync to the nodes subgraph when authenticated.

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│                       UI Layer                           │
│                                                          │
│  CardQuickMenu.svelte  ←→  /wishlist (two-panel page)    │
│  (Save to List picker)     SideNav  ←→  UserMenu         │
└───────────────┬─────────────────────────┬────────────────┘
                │                         │
                ▼                         ▼
        ┌──────────────────────────────────────────┐
        │        wishlistStore.svelte.ts            │
        │       (Svelte 5 runes — $state)          │
        │  - items: ListItem[]                     │
        │  - lists: CustomList[]                   │
        │  - loaded / syncing flags                │
        │  - idMap: local→backend ID resolution    │
        └───────┬────────────────┬─────────────────┘
                │                │
        ┌───────▼──────┐  ┌─────▼──────────────────┐
        │  localStorage │  │  GraphQL (nodes)        │
        │  + IndexedDB  │  │  collections / items    │
        │  (instant)    │  │  (background sync)      │
        └──────────────┘  └────────────────────────┘

Persistence Strategy

The store uses a three-tier persistence model:

Write Path

Every mutation (add/remove/update) follows:

1. Optimistic update — $state arrays mutated immediately
2. localStorage sync — JSON.stringify written synchronously
3. IndexedDB write — idbSet (fire-and-forget async)
4. Backend sync — GraphQL mutation (fire-and-forget, errors logged to console)

Read Path (on load)

1. localStorage read (synchronous — instant hydration)
2. IndexedDB read (async — may override localStorage with fresher data)
3. Backend fetch (async — merges server collections into local state, if authenticated)

Components

`CardQuickMenu.svelte`

The primary entry point for saving items. Lives on product cards, service cards, and lobby tiles.

Key derived values:

let effectiveId = $derived(itemId || product?.id || '');
let effectiveName = $derived(itemName || product?.name || '');
let effectiveHandle = $derived(maletHandle || product?.maletHandle || '');
let effectiveSlug = $derived(product?.slug || '');

These derived values ensure the malet handle and slug are always resolved, even when individual props aren't passed — falling back to the product (ComparisonProduct) object.

`/wishlist` Route

A two-panel management page. SSR is disabled (ssr = false) because the page reads from IndexedDB/localStorage.

Left sidebar: List names with item counts, create/rename/delete actions. Main area: Item grid/list with quantity steppers, inline notes, price totals, CSV export.

Item links resolve to /{maletHandle}/item/{slug || id}. If maletHandle is empty, falls back to /search?q={name}.

Navigation Entry Points

• SideNav (primaryRoutes array) — "My Lists" with actions/heart icon
• UserMenu (avatar dropdown) — "My Lists" button after "My Murchases"

Store: `wishlistStore.svelte.ts`

Types

interface ListItem {
  id: string;
  type: 'product' | 'service' | 'malet';
  name: string;
  handle?: string;
  slug?: string;
  imageUrl?: string;
  price?: number;
  currency?: string;
  maletHandle: string;
  maletName: string;
  addedAt: number;
  listId: string;
  quantity: number;
  note?: string;
}

interface CustomList {
  id: string;
  name: string;
  emoji: string;
  createdAt: number;
  description?: string;
  visibility: 'private' | 'unlisted' | 'public';
}

Actions

ID Resolution

The store maintains an idMap: Map<string, string> that maps local IDs to backend IDs:

• List IDs: col_<timestamp> → backend collection ID (mapped after createCollection response)
• Item IDs: <entityId>:<listId> → backend CollectionItem ID (mapped after addCollectionItem response)

GraphQL API (`$lib/queries/collections.ts`)

Queries

Mutations

All mutations are guarded by GqlAuthGuard and ownership checks in the backend resolver.

Migration

The store includes a migrateItems() function that handles legacy data:

• collectionId → listId (field rename)
• Missing quantity → defaults to 1
• Missing maletHandle → falls back to handle or 'unknown'

Integration Guide

To add the "Save to List" action to a new surface:

1. Import CardQuickMenu from $lib/components/catalog/CardQuickMenu.svelte
2. Pass product metadata props: itemId, itemName, imageUrl, price, currency, maletHandle, maletName
3. Optionally pass a full product (ComparisonProduct) object for slug and handle resolution
4. The component handles all state management internally

<CardQuickMenu
  product={comparisonProduct}
  type="product"
  itemId={product.id}
  itemName={product.name}
  imageUrl={coverImage}
  price={product.basePrice}
  currency="USD"
  maletHandle={maletHandle}
  maletName={maletName}
/>

Related

• Social Graph — Follow system and user connections
• Privacy & Security APIs — Content visibility and data privacy controls
• Community Features — Social graph and inter-Visitor interactions