Design a Wishlist & Gift Registry

Problem statement

Design a platform where users save items for later in a personal wishlist, or create a public gift registry (wedding, baby, housewarming) that other people can purchase from. When an item is purchased from a registry, its remaining quantity must update so two guests do not buy the same gift, and the owner must be notified without spoiling the surprise.

This looks like a simple list-crud feature. It is not. The moment a second human can act on the same list, three hard problems appear. First, a registry item is a scarce resource: the last remaining unit of 'crib' can be claimed by two guests at the same instant, so claiming needs exclusive-ownership semantics, not a boolean flag. Second, availability has two sources of truth: the registry's own quantity and the warehouse inventory behind the SKU, and they reconcile asynchronously. Third, privacy is asymmetric: the owner sees everything including who bought what for thank-you tracking, while guests see only what the owner has shared, and the buyer's identity is usually hidden from the owner until after the event.

The two invariants

Invariant one is claiming correctness: for each registry item unit, at most one guest may hold an active claim at a time, and a claim must survive retries, duplicate checkouts, and network partitions without double-gifting. Invariant two is privacy containment: an unauthenticated guest with a share link must never be able to enumerate the owner's other lists, see buyer identities, or mutate quantities outside the granted scope.

Everything else, from caching to notifications, is optimization inside those two invariants. A wishlist is a read-mostly personal bookmark store. A registry is a coordination protocol between strangers over scarce inventory.