Org Web Adapter

Editing hungryroot/brand/exp242-favorites-tab-backend-review.org

:PROPERTIES:
:ID:       2ed3da6a-7f21-4027-b51f-7736b245b64f
:END:
#+title: Favorites Tab — Backend API Review

* TL;DR

Today's APIs cannot support a paginated, mixed product+recipe Favorites
tab with occasion filters and "sort by recent" without new backend work.

- *All tab (mixed list):* No unified endpoint. v2 favorites endpoints
  return ID-only lists with no pagination or sort.
- *Occasion filters:* Breakfast works differently for products vs
  recipes. "Lunch + Dinner" and "Snacks + More" are client labels — not
  backend enums. Products have no =is_lunch=/=is_dinner= flags.
- *Sort by recent:* Existing =is_recent= means "in recent orders", not
  "recently favorited". Join tables have =create_date= but it is not
  exposed in any API.
- *Pairing text:* All CMS content (=featured_quote=,
  =short_instruction_html=). Favorites store no user text.
- *Recommendation:* New =GET /api/v3/customers/{customer_id}/favorites/=
  with pagination, =occasion= filter, and =ordering=-favorited_at=.

* Executive Summary

The proposed mobile Favorites tab requires capabilities that do not exist
today. A new unified v3 endpoint is the right approach. Keep existing v2
POST/DELETE favorites endpoints for write operations.

One terminology fix: *Breakfast is not a =dish_type= in the backend.*
=DishType= means recipe format (Stir-Fry, Burger, Tacos). Meal-occasion
filtering uses different mechanisms on products vs pairings.

* Current API Landscape

** Dedicated v2 favorites endpoints (ID lists only)

| Method | Path | Returns |
|--------+------+---------|
| GET/POST | =/api/v2/customers/{id}/favorite_pairings/= | =[{"pairing_id": N}]= |
| DELETE | =/api/v2/customers/{id}/favorite_pairings/{pairing_id}/= | 204 |
| GET/POST | =/api/v2/customers/{id}/favorite_products/= | =[{"product_id": N}]= |
| DELETE | =/api/v2/customers/{id}/favorite_products/{product_id}/= | 204 |

*Files:*
- =app/rest/customer_favorites.py=
- =app/rest/customer_favorite_products.py=
- =app/models/customer_favorite_pairing.py=
- =app/models/customer_favorite_product.py=

*Limitations:*
- =limit= query param only — no =offset=, =count=, or =next=
- No sort order (OpenAPI: "does NOT have caching or a custom sort order")
- No occasion filtering
- No card/detail payload — clients must hydrate separately

** v2 list endpoints (full objects, separate lists)

| Endpoint | Pagination | Favorite filter |
|----------+------------+-----------------|
| =GET /api/v2/products/?customer_id=X&is_favorite=true= | limit/offset | yes |
| =GET /api/v2/pairings/?customer_id=X&is_favorite=true= | limit/offset | yes |

These work for *separate* product or pairing feeds but cannot produce one
interleaved "All" tab with a single sort order.

** v3 endpoints (partial coverage)

| Endpoint | Favorites support |
|----------+-------------------|
| =GET /api/v3/customers/{id}/pairings/?is_favorite=true= | Lightweight IDs + liked/is_merchandized |
| =GET /api/v3/pairings/?ids=...= | Full static pairing data (no favorite flag) |
| =GET /api/v3/products/?ids=...= | Full static product data (no =is_favorite= filter) |

No v3 CRUD for favorites. No v3 customer favorite products list.

* Answers to Open Questions

** 1. Under "All", are we mixing products and recipes?

*Yes — intended UX, but no API supports it today.*

Workaround (not recommended for production):
1. Fetch both v2 favorite ID lists
2. Merge client-side
3. Hydrate via =/api/v3/products/?ids=...= and =/api/v3/pairings/?ids=...=

This breaks at scale: no server-side pagination, no stable interleaved
sort, minimum two round-trips.

**Recommended response shape for new endpoint:*

#+begin_src json
{
  "count": 42,
  "next": "...",
  "results": [
    {"item_type": "pairing", "id": 463891, "favorited_at": "2026-05-18T..."},
    {"item_type": "product", "id": 1210, "favorited_at": "2026-05-17T..."}
  ]
}
#+end_src

Clients hydrate card data via existing v3 bulk endpoints, or the new
endpoint can optionally =expand=card= to embed card fields server-side.

** 2. "Breakfast is a dish_type today" — will that work?

*No — not as stated.* This is a common confusion.

| Concept | Products | Pairings (recipes) |
|---------+----------+--------------------|
| Dish type (Stir-Fry, Burger…) | M2M =dish_types= — suggested use, not meal occasion | FK =dish_type= — recipe format |
| Meal occasion (Breakfast, Lunch…) | Boolean flags: =is_breakfast=, =is_snack=, =is_sweet=, =is_fruit=, =is_kid_snack= | Occasion tags: Breakfast-Friendly (47), Lunch-Friendly (48), Dinner Recipe (173) |

If mobile labels a filter "Breakfast" but passes =dish_types=..., that is
likely incorrect for recipes unless using a different screen's filter
model.

*** Occasion tab → API mapping

| Tab | Pairings filter | Products filter |
|-----+-----------------+-----------------|
| All | (none) | (none) |
| Breakfast | =occasion_tags=47= | =is_breakfast=true= |
| Lunch + Dinner | =occasion_tags=48,173= | *No native flag* — see open question |
| Snacks + More | No exact backend enum | =is_snack= OR =is_sweet= OR =is_fruit= OR =is_kid_snack= |

Backend strings "Lunch + Dinner" and "Snacks + More" do *not* exist in
this repo. Closest concepts:

- =OccasionGroupIDs.MEALS= (pk=1) — =plan_service/const.py=
- =OccasionGroupIDs.THROUGHOUT_THE_DAY= (pk=2) — Breakfast, Snacks,
  Sweets, Fruit in =plan_service/fixtures/occasions.json=

*Recommendation:* Define a single backend param on the new endpoint,
e.g. =occasion=breakfast|meals|snacks_and_more=, and let the server map
to the correct product booleans + pairing occasion tags. Do not expose
raw =dish_types= for meal-occasion tabs.

*** Open question: "Lunch + Dinner" for products

Products have no =is_lunch=/=is_dinner= flags. Options:

1. *Inverse heuristic:* meal product = NOT (=is_breakfast= OR =is_snack=
   OR =is_sweet= OR =is_fruit= OR =is_kid_snack=) — simple but imprecise
2. *Occasion tags on products* via existing =occasion_tags= filter in
   =app/rest/product.py= — only works if products are tagged consistently
3. *Recipes-only filter:* Lunch+Dinner tab shows pairings only; products
   appear in All/Breakfast/Snacks — simplest but inconsistent UX

Align with mobile/design before implementing.

** 3. No unified endpoint — pagination requirement

*Confirmed gap.*

Existing v2 favorites GET only supports =limit= truncation:

#+begin_src python
favorite_pairings = obj.favorite_pairings.values(pairing_id=F("pk"))
limit = self.context["request"].query_params.get("limit")
if limit and limit.isdigit():
    favorite_pairings = favorite_pairings[: int(limit)]
#+end_src

File: =app/rest/customer_favorites.py=

Both through models already have =create_date= (migration
=app/migrations/0697_customerfavoriteproduct_customerfavoritepairing_and_more.py=)
which can serve as =favorited_at=.

Discovery collections use =item_type= discrimination
(=discovery_home/const.py= =CollectionItemType=) but never mix types in
one collection — favorites would be the first truly mixed-type paginated
feed.

** 4. Product card mockup — what fields exist?

There is no =ProductCardSerializer=. Closest references:

*** Option A — Discovery home card (richest, browse carousels)

=CollectionProductSerializer= in =discovery_home/views/v2/collection.py=

- Image: =card_image_url=
- Text: =name=, =description=, =brand_name=
- Metadata: =badges=, =points=, =points_after_discount=, =category_name=,
  =spicy_level=, =is_new=
- Occasion hints: =is_breakfast=, =is_snack=, =is_sweet=, =is_fruit=

*** Option B — Lighter list card

=ProductDetailListSerializer= in =app/rest/product.py=

- =card_image_url=, =name=, =description=, =brand_name=, =points=,
  =rating=, occasion booleans

*** Option C — v3 static bulk

=ProductSerializer= in =app/rest/v3/product.py=

- =card_image_url=, =name=, =points=, =brand_name=, =rating=

*** Suggested product card fields for design mockups

| UI element | API field |
|------------+-----------|
| Hero image | =card_image_url= |
| Title | =name= |
| Subtitle | =brand_name= or =description= (truncate) |
| Badges | =badges[]= (personalized) |
| Points | =points= / =points_after_discount= |
| Type pill | =item_type: "product"= (from unified endpoint) |

Recommend matching =CollectionProductSerializer= if Favorites should look
like Discover/browse cards. Cards need a visual *type indicator* (product
vs recipe) since pairings use =featured_img_url= + =featured_quote=
while products use =card_image_url= + =description=.

Pairing card baseline: =PairingListSerializer= (=app/rest/pairing.py=) or
=CollectionPairingSerializer= (=discovery_home/views/v2/collection.py=).

** 5. "Sort by recent" — new param needed

*Correct — and clarify semantics first.*

Existing =is_recent= on products/pairings means *"in customer's recent
orders"*, not "recently favorited":

#+begin_src python
recent_order_ids = list(
    CustomerOrderService(self._customer).get_recent_orders().values_list("pk", flat=True)
)
return queryset.filter(orders__in=recent_order_ids).distinct()
#+end_src

File: =app/rest/v3/pairing.py=

Neither =/api/v2/.../favorite_*= nor =/api/v3/customers/.../pairings/=
exposes sort-by-favorited-date.

*Good news:* Join tables have =create_date= but it is not exposed in any
API today.

For "sort by recently favorited":
- Add =ordering=-favorited_at= on the new unified endpoint
- Expose =favorited_at= (from through-model =create_date=) in response
- Do *not* reuse =is_recent= — different meaning

If product also wants "recently ordered favorites," that could be a
separate =ordering=-last_ordered_at= computed from order history —
significantly more expensive.

** 6. Text on favorited pairings — user generated?

*No. All system/CMS content.*

Favorite record stores only =(customer, pairing)= — no text field:

#+begin_src python
class CustomerFavoritePairing(BaseModelV1):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    pairing = models.ForeignKey(Pairing, on_delete=models.CASCADE)
#+end_src

File: =app/models/customer_favorite_pairing.py=

Text on pairing cards comes from the *Pairing* model:
- =featured_quote= — CMS quote + attribution ("quote | attribution")
- =short_instruction_html= — CMS cooking instructions
- =name=, =nutrition_info= — also system content

Same for products: =name=, =description= are CMS fields. Users can
favorite/unfavorite but cannot attach notes.

* Proposed Architecture

#+begin_example
Current (insufficient):
  v2 favorite_products     → IDs only, no sort
  v2 favorite_pairings     → IDs only, no sort
  v2 products?is_favorite  → paginated, products only
  v2 pairings?is_favorite  → paginated, pairings only

Proposed:
  GET v3/customers/{id}/favorites/  → paginated union
  GET v3/products?ids=...             → hydrate product cards
  GET v3/pairings?ids=...             → hydrate pairing cards
  v2 POST/DELETE favorites            → unchanged (writes)
#+end_example

* Interim Workaround (No Backend Changes)

Works for separate sections or type-specific tabs, *not* a unified sorted
"All" feed.

| Tab | Products | Pairings |
|-----+----------+----------|
| All | =GET /api/v2/products/?customer_id=X&is_favorite=true&limit=20&offset=0= | =GET /api/v2/pairings/?customer_id=X&is_favorite=true&limit=20&offset=0= |
| Breakfast | add =is_breakfast=true= | add =occasion_tags=47= |
| Lunch+Dinner | *no clean filter* | add =occasion_tags=48,173= |
| Snacks+More | filter per-flag client-side or multiple calls | *no clean filter* |

* Recommended Backend Scope

** New endpoint

=GET /api/v3/customers/{customer_id}/favorites/=

Response: ={item_type, id, favorited_at}= + optional expanded card payload

** Implementation sketch

1. UNION query over =customer_favorite_products= and
   =customer_favorite_pairings= through tables
2. Use through-model =create_date= as =favorited_at=
3. Apply occasion filter per item type before union
4. Paginate on unified queryset
5. Keep v2 POST/DELETE favorites endpoints unchanged

** Tests

- Pagination (limit/offset, count, next)
- Occasion filter per item type
- Sort order (=-favorited_at= default recommended)
- Empty states
- Auth (=IsCustomerPathAuthorized=)

** No migration needed

Timestamps already exist on through tables (migration 0697).

** Out of scope (unless requested)

- v3 favorite products personalized list (mirror of v3 pairings)
- User-generated favorite notes
- Changing v2 write endpoints

* Risks and Callouts

- *Occasion filter parity* between products and pairings is asymmetric —
  needs product/design sign-off on "Lunch + Dinner" product logic
- *Re-favoriting* after unfavorite: =create_date= reflects first
  favorite, not re-favorite (unless through row is updated on re-add —
  verify desired behavior)
- *Default sort* when no =ordering= param: recommend =-favorited_at= for
  Favorites tab UX
- *Performance:* UNION + occasion joins should use existing indexes on
  through tables; evaluate EXPLAIN if customer favorite counts are large
- *Do not confuse =is_recent= with recently favorited=* — document in
  OpenAPI

* Open Decisions

- [ ] Confirm "Sort by recent" means =favorited_at= (not =is_recent=/order
      history)
- [ ] Align occasion tab mapping with mobile/design — especially
      Lunch+Dinner for products and Snacks+More for pairings
- [ ] Decide default sort when no =ordering= param
- [ ] Decide re-favorite behavior for =favorited_at= timestamp

* Key File References

| Topic | Files |
|-------+-------|
| v2 favorites APIs | =app/rest/customer_favorites.py=, =app/rest/customer_favorite_products.py= |
| Through models | =app/models/customer_favorite_pairing.py=, =app/models/customer_favorite_product.py= |
| v2 product list + filters | =app/rest/product.py= |
| v2 pairing list + filters | =app/rest/pairing.py= |
| v3 customer pairings | =app/rest/v3/pairing.py= |
| v3 products | =app/rest/v3/product.py= |
| Product card serializers | =discovery_home/views/v2/collection.py=, =app/rest/product.py= |
| Occasion constants | =app/const.py= (=Occasion=), =plan_service/const.py= (=OccasionGroupIDs=) |
| Occasion tags | =app/models/tag.py= (IDs 47, 48, 173), =app/fixtures/Tag.json= |
| DishType (recipe format) | =app/models/dish_type.py=, =app/fixtures/DishType.json= |