---
name: gift-registry
description: Use when working on the gift registry — Gift and GiftClaim models, the derived quantity_remaining / is_fully_claimed logic, the public registry grid and reserve-gift modal, or the locked-transaction claim that prevents over-claiming under concurrency.
---

# Gift Registry Domain

> Stub — fleshed out during Phase 5. Captures the rules that govern gifts and claims.

## Scope

- `Gift` model + `gifts` table (name, description, image_path, price, currency MYR, category,
  quantity_needed, purchase_url, priority, is_active).
- `GiftClaim` model + `gift_claims` table (gift_id cascade, guest_name, guest_email,
  quantity_claimed, message).
- Public Livewire registry grid + reserve-gift modal.

## Derived logic — single source of truth on the Gift model

- `quantity_claimed_total` = sum of related `gift_claims.quantity_claimed`.
- `quantity_remaining` = `max(0, quantity_needed - quantity_claimed_total)`.
- `is_fully_claimed` = `quantity_remaining === 0`.

## Rules

- A claim may **never** exceed `quantity_remaining`. Enforce server-side inside a DB
  transaction using `lockForUpdate()` on the gift row so concurrent claims cannot over-claim.
- Reserve modal: guest name (required), email (optional), quantity (capped at remaining),
  note (optional). On confirm, create the claim and update remaining live.
- Fully-claimed gifts render a "Taken / Fully reserved" state with reservation disabled.
- Eager-load claims to avoid N+1 on the grid. Filter by category, sort by priority.

## See also

- skills/liquid-glass — card and modal visual treatment.
- AGENTS.md → Domain rules.