Org Web Adapter

Editing hungryroot/popsicle/exp-242-favorites.org

:PROPERTIES:
:ID:       5c0f7bd3-053e-47ed-a707-507d36f1666a
:END:
#+title: Exp 242 - Favorites + User Cookbooks

* Exec (TLDR) summary

Expose a unified Favorites surface as a thin *pass-through proxy* over the
existing =CustomerFavoritePairing= / =CustomerFavoriteProduct= tables. Those
tables remain the source of truth. The new
=/api/v3/customers/{id}/cookbooks/favorites/= endpoint synthesizes a
Cookbook-shaped *read* façade from legacy rows at request time.

*For the MVP, writes (favoriting / unfavoriting) continue to use the existing
V2 endpoints* — no V3 POST/DELETE is shipped in this release. *No* schema
change to =Cookbook=. *No* data migration, backfill, dual-write, advisory
locks, or cutover DC.

Occasion bucket mappings (see Figma for "Breakfast", "Lunch + Dinner"
pill buttons) are server-owned via a new DynamicConfig public setting.

The Favorites response envelope mirrors =CookbookSerializer= field-for-field
where applicable (with null/empty defaults) and diverges only on pagination:
items live in a single synthetic =sections[0].items[]= section that is
paginated, rather than the static =sections[*]= of a curated cookbook.

When a user shares a cookbook, create "shell" Cookbook instance with a unique
slug and a new =CookbookType= of =favorites= which builds on
[[https://hungryroot.atlassian.net/wiki/spaces/BA/pages/1430945793][Exp 232 - Cookbooks]] and is exposed via the existing cookbook API:
=/api/v3/cookbooks/<slug>/=.

* API client summary

What client engineers need to integrate Favorites. The entire v3 surface is
*read-only*; favoriting / unfavoriting still goes through the existing v2
endpoints. v2 writes hit the same source-of-truth tables, so they show up in
the next v3 read with no sync step.

** New v3 read endpoints

- =GET /api/v3/customers/{customer_id}/cookbooks/favorites/= :: the caller's
  favorites as a Cookbook-shaped envelope (mixed pairings + products).
  - Query params:
    - =filter= (bucket slug, e.g. =lunch_dinner=)
    - =ordering= (default =-create_date=, or =create_date=; any other value → *400*)
    - =limit= / =offset= (DRF pagination)
  - Items live at =sections[0].items[]=.
  - =cookbook_type= and =kind= are both ="favorites"=.
  - Each item =id= is an opaque composite (=pairing-{id}= / =product-{id}=).
- =GET /api/v3/cookbooks/{id|slug}/= :: public, shareable cookbook by slug.
  - Same response shape.
  - Used for shared / user-created favorites cookbooks
    (=cookbook_type="favorites"=).

** Occasion filters

- Fetch the bucket → tag mapping from the public DynamicConfig
  =api.favorites.occasion_filters= on app launch, cache for the session, then
  pass the bucket display name as =?filter=Lunch & Dinner=.
- Bucket display names ("Breakfast", "Lunch & Dinner", "Snacks & Meals") are
  the DC keys and the =filter= param values; no client-side mapping needed.

** Writes — use existing v2 endpoints (unchanged)

- =POST /api/v2/customers/{customer_id}/favorite_pairings/= ·
  =DELETE /api/v2/customers/{customer_id}/favorite_pairings/{pairing_id}/=
- =POST /api/v2/customers/{customer_id}/favorite_products/= ·
  =DELETE /api/v2/customers/{customer_id}/favorite_products/{product_id}/=

*Rendering note:* if =cookbook_type == "favorites"=, iterate
=sections[0].items[]=; otherwise use the curated-cookbook =sections[*].items[]=.
Every per-item field matches =CookbookItemSerializer=.

* Overview

- POD :: Brand
- Product Requirements / Brief :: [[https://docs.google.com/document/d/1jHbKNiupiZp2Ece2PhPienjJ4kC8EUvkJorzRpa1j6I/edit?tab=t.kupfnodp89p8][Google Doc]]
- Design Document :: TODO
- Figma :: [[https://www.figma.com/design/ewERdxFs62fj2MiXjiS1b2/Exp-xxx--New-Bottom-Navigation?node-id=533-43073&p=f&m=devPrototype][New Bottom Navigation]]
- Epic :: [[https://hungryroot.atlassian.net/browse/EP-650][EP-650]]
- Experiment :: Exp 242
- Slack Channel :: [[https://hungryroot.slack.com/archives/C0B4QA7Q05A][#exp-242]]
- Target Complete Date (Backend) :: TODO
- Target Launch Date (Feature) :: TODO
- WEB spec :: TODO

** People

| Role                          | Review Approved (add initials) |
|-------------------------------+--------------------------------|
| Stakeholder Lead - TODO @     |                                |
| Product Lead - TODO @         |                                |
| Technical Team Lead - TODO @  |                                |
| Technical Primary - TODO @    |                                |
| Technical Secondary - TODO @  |                                |
| QA Lead - TODO @              |                                |
| Data Lead - TODO @            |                                |
| BFL Lead - TODO @             |                                |
| Additional Technical - TODO @ |                                |

** Timeline and milestones

| Item                           | Date | Description | Key Stakeholder Sign-off              |
|--------------------------------+------+-------------+---------------------------------------|
| Spec review complete           |      |             | Primary Dev / Dev Lead / Project Lead |
| Code complete                  |      |             | ...                                   |
| QA starts                      |      |             | ...                                   |
| P1 features staging roll out   |      |             | ...                                   |
| P1 features production rollout |      |             | ...                                   |

** Background

The mobile apps and web site want a unified *Favorites* tab that mixes
favorited recipes (pairings) and products in a single list, filterable by
occasion buckets (All, Breakfast, Lunch+Dinner, Snacks+More) and sortable
by recency. Today favorites are split across two flat tables
(=CustomerFavoritePairing=, =CustomerFavoriteProduct=) with no shared ordering
and no pagination strategy. At the same time, we want to grow engagement with
curated Cookbooks ([[https://hungryroot.atlassian.net/wiki/spaces/BA/pages/1430945793][Exp 232]]) and enable *user-created Cookbooks* in the same
surface.

The Favorites surface and Cookbooks surface look superficially similar —
heterogeneous lists of pairings + products — but they have very different data
shapes. Favorites are one-row-per-favorited-thing with no ordering or notes;
curated Cookbooks are sectioned, ordered, staff-authored. Conflating them
forces either a large data migration (move all favorites into =CookbookItem=
rows, dual-write during cutover, deprecate the legacy tables) or a thin proxy
that gives the client the Cookbook-shaped response it wants without moving any
data. This spec takes the proxy route.

*** High-Level Solution

- *V3 read endpoint proxies the legacy favorite tables.* The new
  =/api/v3/customers/{id}/cookbooks/favorites/= endpoint synthesizes a
  Cookbook envelope from =customer.favorite_pairings= +
  =customer.favorite_products= at request time. No =Cookbook= rows are created
  for Favorites.
- *Writes stay on V2 for the MVP.* Clients continue to favorite/unfavorite via
  the existing =/api/v2/.../favorite_pairings/= and =/favorite_products/=
  endpoints. Because the V3 read proxies the same tables, V2 writes are
  immediately reflected in the next V3 fetch. No dual-write or sync logic
  needed.
- *Truth stays in* =CustomerFavoritePairing= / =CustomerFavoriteProduct=. The
  legacy =/api/v2/customers/{id}/favorite_pairings/= and =/favorite_products/=
  endpoints stay live. =get_customer_favorite_pairings= (used for
  =is_favorited= enrichment in pairing list responses) keeps working unchanged.
- *Occasion filtering is server-driven via a public DynamicConfig.* The
  favorites endpoint accepts a =filter= query parameter whose value is a bucket
  display name (a key of the DC dict =api.favorites.occasion_filters=, e.g.
  ="Lunch & Dinner"=). Each bucket maps to an =OccasionBucket= with separate
  =pairing_tags= and =product_tags= lists of =Tag= IDs, so pairings and
  products can be filtered by different tag sets.
- *Response mirrors* =CookbookSerializer=. Every top-level field on the
  curated-Cookbook detail response is present on the Favorites envelope — with
  null/empty defaults where Favorites has no analog (e.g. =author=,
  =collections=, =description=, =hero_image=). The only intentional divergence
  is pagination: items live in a single synthetic =sections[0].items[]= section
  that is paginated, rather than the static =sections[*]= of a curated
  cookbook. Clients branch on =cookbook_type == "favorites"= for the items
  iteration; every other render path is shared.
- *User-created Cookbooks* will require adding one new enum value of
  =favorites= to allow distinguishing user-created cookbooks from
  marketing-curated. Existing favorites tables are still used to synthesize
  the items in the user-created cookbook. The =slug= field will be used to
  create a unique share URL for each cookbook. Cookbooks will be public by
  default, with no way to disable sharing, except marking them as
  =is_active=False=.

* Experiment

*Experiment cleanup if it wins:* Nothing to roll forward on the data side —
favorites never moved. Cleanup is limited to (a) removing the legacy
=/api/v2/.../favorite_pairings/= and =/favorite_products/= REST views once all
supported app versions have cut over to the v3 favorites endpoint, and (b)
keeping the user-cookbook code. The =api.favorites.occasion_filters= DC and
lookup endpoint stay live indefinitely (they own the bucket mapping).

*Experiment cleanup if it loses:* Delete the new view files, the
=FavoritesService=, the bucket-mapping DC, the lookup endpoint, and any
Cookbooks of CookbookType =favorites=. No data to roll back. The
=CookbookType.FAVORITES= enum value can stay as a harmless additive constant.

** Dynamic Configs

- =api.favorites.occasion_filters= :: JSON dict mapping occasion bucket display
  name (e.g. ="Lunch & Dinner"=) to an =OccasionBucket= with separate
  =pairing_tags= and =product_tags= lists of =Tag= IDs. Read via a cached
  getter on =DynamicConfig= (=@cache_memoize(300)=).

** Launch Plan

TBD with Product. See *Cutover Plan* below for the rollout sequence.

* Implementation

All changes land in =cookbooks/= (Favorites read endpoint + occasion-filter
lookup endpoint + =CookbookType.FAVORITES= enum value) and =app/= (DC
registration, getter). The legacy favorite REST views in =app/rest/= remain in
place; nothing is deprecated until clients have cut over.

** Apps

- =cookbooks= :: EXTEND (new endpoints + service; add =FAVORITES = "favorites"=
  to =CookbookType=; no other model changes for Favorites)
- =app= :: register the new DC (=app/constants/dynamic_config.py=), add the
  typed getter (=app/models/dynamic_config.py=), optional admin validation
  rule (=app/admin/dynamic_config.py=). Legacy =CustomerFavoritePairing= /
  =CustomerFavoriteProduct= remain authoritative — no model changes there.

** Models & Fields

*** Favorites

*No schema changes.* No new tables, no new fields. Adds =FAVORITES =
"favorites"= to the existing =CookbookType= choices in =cookbooks/models.py=
as a serialization marker on the synthesized envelope. No migration needed —
no Cookbook rows are written with this value.

The proxy reads through-rows directly from =CustomerFavoritePairing= /
=CustomerFavoriteProduct= so the sort by =create_date= reflects favoriting
time (not when the underlying Pairing / Product was created):

#+begin_src python
# Already defined in app/models/customer_favorite_pairing.py
# and app/models/customer_favorite_product.py

CustomerFavoritePairing.objects.filter(customer=customer)
CustomerFavoriteProduct.objects.filter(customer=customer)
#+end_src

*** User-Created Cookbooks

If user-created Cookbooks are in scope for this release, add two fields to
=Cookbook=:

#+begin_src python
class CookbookType(models.TextChoices):
    THEMATIC = "thematic", "Thematic"      # current Exp 232 cookbooks
    PERSONALITY = "personality", "Personality"  # current Exp 232 cookbooks
    FAVORITES = "favorites", "Favorites"   # Added as part of Exp 242
#+end_src

Notes:

- Customer mapping to a Cookbook is done via the =CookbookAuthor= table which
  links to the =User= table. This m

*** Occasion-filter mapping

No table. Server-side bucket-slug → tag mapping lives in the
=api.favorites.occasion_filters= DC. The =slug= → =Tag.id= map for the hybrid
product filter lives in =cookbooks/const.py=. See *Occasion Filters* below.

** APIs

*** Retrieve Personal Favorites Cookbook

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

Returns the caller's favorites as a synthesized Cookbook envelope with mixed
pairing+product items. The envelope mirrors =CookbookSerializer=
field-for-field for top-level fields (with null/empty defaults where Favorites
has no analog) and diverges only on the items wrap — items live in a single
synthetic =sections[0].items[]= section that is paginated, rather than the
static =sections[*]= of a curated cookbook. Reads directly from the legacy
favorite tables; no =Cookbook= rows are created.

*Query Parameters:*

- =filter= (string, optional) :: A single occasion bucket display name (a key
  of =api.favorites.occasion_filters=, e.g. =Lunch & Dinner=). The server
  resolves it to an =OccasionBucket= and filters pairings by =pairing_tags=
  and products by =product_tags= independently. Unknown value → =400=. Omit
  for the full favorites set.
- =ordering= (string, default =-create_date=) :: One of =-create_date= (recent
  first), =create_date= (oldest first). Any other value raises a 400 (the
  service raises =ValueError=, which the view translates). Custom
  position/reordering is not supported in Phase 1; the underlying tables don't
  store a position.
- =limit=, =offset= :: Offset-based pagination (DRF =LimitOffsetPagination=
  shape). The response carries =count= plus =next= / =previous= absolute page
  URLs (=null= at the ends). Internally the service returns =next_offset= /
  =previous_offset= integers; the view renders them into URLs from the request
  (it owns the absolute URI + route). See *Services* below.

*Response:*

#+begin_src json
{
  "id": null,
  "slug": "favorites-12345",
  "name": "My Favorites",
  "description": null,
  "hero_image": null,
  "is_featured": false,
  "is_active": true,
  "sort_order": 0,
  "cookbook_type": "favorites",
  "kind": "favorites",
  "owner_id": 12345,
  "author": null,
  "dietary_tag_ids": [],
  "collections": [],
  "pairing_count": 30,
  "product_count": 12,
  "count": 42,
  "next": "/api/v3/customers/12345/cookbooks/favorites/?limit=20&offset=20",
  "previous": null,
  "sections": [
    {
      "id": null,
      "name": null,
      "position": 0,
      "items": [
        {
          "id": "pairing-125451",
          "item_type": "pairing",
          "position": 0,
          "pairing_id": 125451,
          "product_id": null
        },
        {
          "id": "product-826",
          "item_type": "product",
          "position": 1,
          "pairing_id": null,
          "product_id": 826
        }
      ]
    }
  ]
}
#+end_src

*Count semantics.* =count=, =pairing_count=, and =product_count= are all
post-filter, pre-pagination — they reflect the =filter= occasion bucket but
not pagination. =count= always equals =pairing_count= + =product_count=. (This
diverges from curated =CookbookSerializer=, whose counts describe the whole
cookbook; Favorites counts describe the filtered set the client is viewing.)

*Item id encoding:* Legacy rows live in two tables with independent PKs, so
the synthesized =id= is a composite string ="pairing-{id}"= /
="product-{id}"=. Mobile clients treat the field as opaque so this shape
difference vs. curated cookbooks is invisible.

*Position:* Reflects the item's global rank in the sorted result set
(offset-aware). On page 2 of a paginated response, the first item's =position=
equals the offset, not 0.

*** Retrieve Shared Favorites Cookbook

=GET /api/v3/cookbooks/{id|slug}/=

Returns the same shape as the Favorites URL above, but public and allows
"sharing" a cookbook using a unique slug field. Recommend an auto-slug
generation approach like Base62-encoded random bytes, which results in slugs
like: =aK7mX2nQ= and used by Spotify and YouTube. Statistically unlikely to
collide over a 13 million generations.

*** Create / Remove Favorites — MVP uses V2 endpoints

For the MVP, the V3 surface is *read-only*. Clients continue to favorite and
unfavorite items via the existing V2 endpoints. Because the V3 read endpoint
proxies the same source-of-truth tables, V2 writes are immediately reflected
in the V3 favorites cookbook on the next fetch — no dual-write or sync code
needed.

*Use these for MVP:*

- =POST /api/v2/customers/{customer_id}/favorite_pairings/= — favorite a
  pairing
- =DELETE /api/v2/customers/{customer_id}/favorite_pairings/{pairing_id}/= —
  unfavorite a pairing
- =POST /api/v2/customers/{customer_id}/favorite_products/= — favorite a
  product
- =DELETE /api/v2/customers/{customer_id}/favorite_products/{product_id}/= —
  unfavorite a product

V3 =POST=/=DELETE= equivalents may be added in a follow-up once we want to
consolidate the favorites surface fully under V3. They are out of scope for
this experiment.

*** Legacy v2 endpoints (unchanged)

The endpoints listed above stay live, backed by the same tables. Apps may
continue to use them indefinitely; the v3 read surface is additive.

Removal of the legacy endpoints is out of scope for this experiment; revisit
once all supported app versions are on v3.

*** User-Created Cookbooks

Neither users nor clients will directly create Cookbooks for the unique share ID,
rather when a user chooses to share, we'll generate a "shell" cookbook on the
fly tied to the user (via =CookbookAuthor= → =User= → =Customer=). No APIs
for creating cookbooks need to be exposed to clients.

** Occasion Filters

Buckets (Breakfast / Lunch+Dinner / Snacks+More) map to lists of =Tag.id=.
The Lunch+Dinner mapping is *server-owned*, stored in a single DynamicConfig
and read by clients via a public DynamicConfig.

*Why server-owned (vs. per-platform UI constants):*

- Single source of truth across iOS, Android, and web — no drift between
  client copies.
- PM can reshuffle bucket contents (or absorb a newly added =Tag=) without a
  client release; one admin edit covers all clients.
- Pattern is idiomatic in the codebase: =marketing.utm_source.redirect=,
  =checkout.dow_priority=, and =cyo2.recommendation_limit= all store
  dict-shaped config validated by Pydantic and cached via =@cache_memoize=.
- Bucket *labels* ("Lunch + Dinner", "Snacks & More") remain client-side copy
  / i18n concern. Only the slug/tag_id mapping list is server-owned.

*DynamicConfig:* =api.favorites.occasion_filters=

- Shape: =dict[str, OccasionBucket]= where each bucket has =pairing_tags:
  list[int]= and =product_tags: list[int]=
- Default value:
  #+begin_src json
  {
    "Breakfast":     {"pairing_tags": [47],      "product_tags": [27,28,29,30,31,32,33,34]},
    "Lunch & Dinner":{"pairing_tags": [48, 173], "product_tags": []},
    "Snacks & Meals":{"pairing_tags": [],        "product_tags": [35,36,37,38,39,40,41,42,43,44,45,46]}
  }
  #+end_src
  =product_tags= for =Lunch & Dinner= pending H&E / RTE tag IDs from prod.
- Validator: =PydanticJSONValidator(OccasionFiltersModel)=.
- Getter: =get_occasion_filters()= in =cookbooks/services.py=. Returns ={}=
  and logs on parse failure (clients see an empty bucket, not a 500).

*Flow:*

1. Client fetches the DC dict on app launch; keys are the display names shown
   in the UI. Result cached on the client for the session.

2. User taps a bucket tab; client passes the display name directly:

#+begin_src shell
GET /api/v3/customers/12345/cookbooks/favorites/?filter=Lunch%20%26%20Dinner
   #+end_src

3. Server looks up the =OccasionBucket=, filters pairings by =pairing_tags=
   and products by =product_tags= independently.

** Services

All business logic lives in =cookbooks/services.py= (alongside
=CookbookService= from Exp 232). For the MVP, only the read path is
implemented; =favorite()= / =unfavorite()= methods are deferred until a future
V3 write surface is in scope.

#+begin_src python
# cookbooks/services.py

from app.models import Customer, CustomerFavoritePairing, CustomerFavoriteProduct
from cookbooks import models
from cookbooks.datatypes import OccasionBucket

class FavoritesService:
    def list_favorites(
        self,
        customer: Customer,
        occasion_bucket: OccasionBucket | None = None,
        ordering: str = "-create_date",
        limit: int | None = None,
        offset: int | None = None,
    ) -> FavoritesEnvelope:
        if ordering not in ("create_date", "-create_date"):
            raise ValueError(...)
        pairing_tags = occasion_bucket.pairing_tags if occasion_bucket else None
        product_tags = occasion_bucket.product_tags if occasion_bucket else None
        pairing_rows = self._collect_pairing_rows(customer, pairing_tags)
        product_rows = self._collect_product_rows(customer, product_tags)
        # ... merge, sort by create_date, paginate, serialize into the Cookbook-shaped envelope ...

@staticmethod
    def _collect_pairing_rows(customer, pairing_tags: list[int] | None):
        if pairing_tags is not None and not pairing_tags:
            return []
        queryset = CustomerFavoritePairing.objects.filter(customer=customer)
        if pairing_tags is not None:
            queryset = queryset.filter(pairing__tags__id__in=pairing_tags).distinct()
        return [...]  # (pairing_id, create_date) rows

@staticmethod
    def _collect_product_rows(customer, product_tags: list[int] | None):
        if product_tags is not None and not product_tags:
            return []
        queryset = CustomerFavoriteProduct.objects.filter(customer=customer)
        if product_tags is not None:
            queryset = queryset.filter(product__tags__id__in=product_tags).distinct()
        return [...]  # (product_id, create_date) rows
#+end_src

Key properties:

- *Read-only for MVP.* Writes route through the existing V2 favorite REST
  views; no new write code is added.
- *Cookbook-shaped envelope.* The returned dict carries every top-level field
  =CookbookSerializer= exposes (=id=, =slug=, =name=, =description=,
  =hero_image=, =is_featured=, =is_active=, =sort_order=, =cookbook_type=,
  =author=, =dietary_tag_ids=, =collections=, =pairing_count=,
  =product_count=) with null/empty defaults where Favorites has no analog.
  =cookbook_type= uses the new =CookbookType.FAVORITES = "favorites"= enum
  value. =kind: "favorites"= and =owner_id= are additive Favorites-specific
  discriminators.
- *Items shape matches* =CookbookItemSerializer=. Each item carries =id=,
  =item_type=, =position=, =pairing_id=, =product_id= — same field names as a
  curated CookbookItem. Items live in a single synthetic =sections[0].items[]=
  section that is paginated, rather than the static =sections[*]= of a curated
  cookbook.
- *Counts.* =count=, =pairing_count=, and =product_count= are all post-filter,
  pre-pagination, taken from the collected row lists (=len(pairing_rows)= /
  =len(product_rows)=) — no extra =count()= queries. =count= always equals
  =pairing_count= + =product_count=.
- *Pagination offsets.* The service owns the pagination math, not URL
  building: it returns =next_offset= / =previous_offset= integers (=None= at
  the ends) computed from =total=, =limit=, =offset=. The view renders these
  into absolute =next= / =previous= URLs, since only the request knows the
  absolute URI + route. Keeps the service HTTP-agnostic and unit-testable.
- *Independent tag filters.* Pairings are filtered by =pairing_tags= and
  products by =product_tags= from the resolved =OccasionBucket=. An empty list
  on either side returns nothing for that type; =None= (no filter) returns all.
- *Through-row reads.* Service queries =CustomerFavoritePairing= /
  =CustomerFavoriteProduct= directly with =.values("...", "create_date")= so
  the sort uses favoriting time, not the underlying Pairing's create date.
- *Ordering validation.* The service raises =ValueError= if =ordering= is
  anything other than ="create_date"= / ="-create_date"=. The view (BE-7818)
  translates this to 400.
- *Position is global rank.* Items' =position= reflects offset-aware rank, not
  page-local index — so page 2 starts at position = offset, not 0.
- *Existing* =get_customer_favorite_pairings= in =app/services/api/pairing.py=
  (used for =is_favorited= enrichment in pairing list responses) keeps working
  unchanged because it reads the same truth tables.
- *Referral codes.* TBD given discussions between engineering and product.

** Caching

Curated Cookbooks continue to use CDN caching from Exp 232. Per-request query
optimization (=.values()= on the through-rows; =.distinct()= on the product
filter to dedupe Tag M2M joins) is sufficient.

** Django Settings

No new app registration. Adds one DC: =api.favorites.occasion_filters=
(see *Occasion Filters* above).

* Cutover Plan

There is no data migration. Cutover is purely client-side.

1. Ship DC with mapped occasion bucket slugs to a list of tag_ids.
2. Mobile + web ship the new Favorites UI: fetch the occasion-filter mapping
   at app launch, render bucket tabs, call the V3 favorites endpoint with the
   appropriate =filter= bucket slug. Favoriting / unfavoriting continues to
   call the existing V2 endpoints.
3. Ramp the experiment by cohort per Product. Compare engagement metrics
   against the holdout running the legacy v2 read surface.

** Risks & Mitigations

| Risk                                                                                                                       | Mitigation                                                                                                                                                                                                                                                                                          |
|----------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Bad DC edit blanks out or corrupts the Lunch+Dinner bucket for all clients at once                                         | Pydantic validator rejects unknown slugs at admin save. Getter returns ={}= on parse failure so clients see an empty bucket, not a crash. Admin audit log + 5-min =cache_memoize= TTL makes revert fast.                                                                                            |
| Client caches the occasion-filter mapping at launch and misses a mid-session DC edit                                       | Acceptable for v1 — bucket reshuffles are infrequent and the next app open picks up the change. If staler behavior becomes a problem, the client can re-fetch on Favorites screen mount or honor a short TTL.                                                                                       |
| Custom user-defined ordering of favorites (drag-to-reorder)                                                                | Not supported in Phase 1. Underlying tables have no position column. If this becomes a requirement, either add a =position= column to the through-tables (additive, defaults to NULL) or revisit the truth-migration approach as a follow-up.                                                       |
| Mobile rendering branches on shape — Favorites returns a single synthetic =sections[0]= that is paginated, while curated Cookbook detail returns static =sections[*]=. | Both shapes share =sections[*].items[]=, so item iteration is identical. Clients branch on =cookbook_type == "favorites"= only to know the section is paginated. Every per-item field and almost every top-level field is identical, so all other render logic is shared. Documented in the API spec and the BE-7818 ticket. |

* Data Analytics

Track:

- Favorites tab views (existing event), with new properties: =filter=
  occasion bucket, =ordering=, page =offset=.
- Per-bucket impressions (client-side; the server can't tell "Lunch+Dinner"
  from the slug list it received).
- Favorite / unfavorite events continue to be emitted by the existing V2
  endpoints; no new BE events for writes in this experiment.
- (Phase 2) User-created cookbook create / edit / share events.

** Segment

TBD with Data.

* Back Office Considerations

** Django Admin

No changes needed for Favorites in Phase 1. Existing admin for
=CustomerFavoritePairing= / =CustomerFavoriteProduct= in =app/admin/= remains
the back-office surface.

The =api.favorites.occasion_filters= DC is edited through the existing
=DynamicConfigAdmin= with a Pydantic validator attached.

For Phase 2 (user cookbooks): extend the existing =cookbooks= admin from Exp
232 to filter by =kind= and =owner=, and make user-owned cookbooks read-only
for staff (avoid editing customer-owned data).

* Observability

Feature-level =structlog= events grouped under ="Favorites v3"=:

- =list_request= — emitted on GET =/cookbooks/favorites/=. Properties:
  =customer_id=, =filter=, =count=, =total= (full favorites set
  count, for power-user monitoring), =limit=, =offset=.
- Parse failure of =api.favorites.occasion_filters= logged at error level
  by the getter (with the raw value snippet).

Favoriting / unfavoriting continues to be logged by the existing V2 endpoints.
No new write-side observability is needed.

* Technical Debt

*Debt incurred*

- Two read surfaces (=/api/v2/.../favorite_pairings/= +
  =/favorite_products/= for V2 reads, and
  =/api/v3/.../cookbooks/favorites/= for the merged V3 read) coexist
  indefinitely, both backed by the same tables. No skew is possible, but two
  view files need maintenance. Cleanup ticket filed for post-cutover removal
  of V2 reads once apps have moved.
- Writes remain split across two V2 endpoints; no consolidated V3 write
  surface yet. Followup ticket if/when needed.
- Slug → tag-id map stored in DC is fragile. Should consider more robust tags
  if this experiment wins.

*Debt avoided vs. the truth-migration alternative considered earlier*

- No lazy backfill, no advisory-lock dance, no bulk sweep command, no
  dual-write code, no skew monitor, no =auto_now_add= corner case.
- No deprecation of =CustomerFavoritePairing= / =CustomerFavoriteProduct=
  tables.

*Debt avoided vs. the UI-owned constant alternative considered earlier*

- No risk of iOS / Android / web drifting from each other when buckets are
  reshuffled.
- No client release required to absorb a new =DishType= row into the
  Lunch+Dinner bucket.

* Open Questions

- *Initial bucket → slug mapping.* Default value for
  =api.favorites.occasion_filters=. See draft in *Occasion Filters*; needs
  design sign-off before launch.
- *Drag-to-reorder favorites.* Not in Phase 1 — underlying tables don't store
  a position. If required, add a =position= column to the through-tables
  (additive) and let the v3 endpoint honor an =ordering=position= query.
- *Sharing / discovery of user cookbooks.* Private by default? "Share to feed"
  surface, with moderation, in scope?

* Ticket Breakdown

** Favorites Proxy (read-only MVP)

| Name                                                                                                              | Estimate | Description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|-------------------------------------------------------------------------------------------------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [[https://hungryroot.atlassian.net/browse/BE-7817][BE-7817]] - =FavoritesService.list_favorites=                  |        1 | Read through-rows from =CustomerFavoritePairing= / =CustomerFavoriteProduct=. Synthesize Cookbook-shaped envelope (every =CookbookSerializer= top-level field with null/empty defaults; =cookbook_type="favorites"= via new enum value). Pairings: =dish_type__slug__in=. Products: hybrid =Q(dish_types__slug__in) \| Q(tags__id__in)= so RTE meals (empty M2M) show under Lunch+Dinner; slug → daypart-tag-id map lives in =cookbooks/const.py=. Tests for empty / mixed / filtered / RTE coverage / dedup / count semantics. |
| [[https://hungryroot.atlassian.net/browse/BE-7818][BE-7818]] - Favorites v3 GET endpoint                          |        1 | =GET /api/v3/customers/{id}/cookbooks/favorites/= (read-only). Serializer, viewset, URL wiring. Translate =ValueError= from the service (invalid =ordering=) to 400. Emit =Favorites v3 / list_request= structlog with =total= kwarg for power-user monitoring. Tests for happy path, occasion filter, pagination, permission checks. *Writes (POST/DELETE) are out of scope* — clients use the existing V2 favorite endpoints.                                  |
| TODO ticket - New CookbookType =favorites= and auto-creation when user "shares" their cookbook                    |        1 | TBD: Need to figure out when, how or why a user would ask to share cookbook. Is it on referral? Creating new =favorites= cookbook for a user should auto-generate a slug based on the Base62-encoded random bytes technique.                                                                                                                                                                                                                              |
| *Total*                                                                                                           |        4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

* Appendix

** Glossary

- *Pairing* :: A recipe in the Hungryroot catalog (=app.Pairing=).
- *Product* :: A SKU in the Hungryroot catalog (=app.Product=).
- *DishType* :: A categorical tag on Pairings (=app.DishType=); 21 rows
  including =salad=, =pasta=, =pizza=, =stir-fry=, =grain-bowl=, etc.
  Identified by stable =slug=.
- *Daypart dish-type Tag* :: A Tag in =TagGroup.LUNCH_DISH_TYPE= (41) or
  =TagGroup.DINNER_DISH_TYPE= (39), e.g. =Tag.ID.LUNCH_SALAD=,
  =Tag.ID.DINNER_PASTA=. Used to categorize RTE / heat-and-eat products that
  don't carry =Product.dish_types=.
- *Curated Cookbook* :: Staff-authored Cookbook from Exp 232.
  =cookbook_type='thematic|personality'=. =CookbookAuthor.user= is null.
- *Favorites (proxy)* :: A customer's favorited pairings + products, rendered
  as a synthesized Cookbook by the v3 read endpoint. Not backed by =Cookbook=
  rows. =cookbook_type="favorites"=.
- *User Cookbook* :: Customer-authored Cookbook. =cookbook_type='favorites'=,
  =owner=CookbookAuthor.user.customer=.

* Inline Review Comments

** Open

- =Extend Cookbook with owner (FK to Customer, nullable)= :: Wally Chang —
  "if a cookbook has both a owner and author, what will this logic look
  like?"
  - Reply (Colin): author should be limited to curated cookbook types and
    not be linked to a customer or user. Owner is the FK that ties a
    cookbook to a particular customer.

- =Favoriting/unfavoriting becomes create/delete of a CookbookItem in that
  customer's Favorites cookbook.= :: Wally Chang — "This requires a client
  change and we'd need to keep bookmark in sync with cookbook items. Have
  you thought more about using cookbook as a proxy instead of migrating all
  the data to cookbook?"
  - Reply (Wally): "i think a dedicated section on how we plan to handle the
    dual-write would be helpful here"
  - Reply (Colin): "damn, I forgot about the proxy idea … let me come up
    with a summary of what that would look like" — addressed by current
    proxy design.

- =MealCategory (NEW, lookup)= :: Wally Chang — "What is this used for?"
  - Reply (Colin): addresses first bullet of Wally's Slack message
    [[https://hungryroot.slack.com/archives/C0B4QA7Q05A/p1779202055262089][here]].

- =breakfast, lunch_dinner, snacks_and_more= :: James Chen — avoid tying API
  params to UI tab names; use stable domain-level enum; let UI map labels to
  that. Follow-up: "are we adding new dish types =breakfast=,
  =lunch_dinner=, =snacks_and_more= specifically for this filter?"
  - Reply (Colin): "no, specific enums for this that would map to existing
    dish types … I'll add a note that we should use existing dish_types and
    let the UI map as needed." — addressed by current dish_type slug param.

- =-created_at= :: James Chen — "Does this mean that the endpoint will
  support both =-= and without =-=?"
  - Reply (Colin): yes.

- =Team prefers shipping the Favorites surface fast and revisiting
  truth-migration as a follow-up= :: Colin — "I think this is exactly where
  we are @James Chen … I'm gonna update this doc to use the pass-through
  model strategy rather than adding fields to the cookbook model"

- =UI defines (in app code) a small constant per platform= :: Colin — "@Wally
  Chang not sure if this is what you had in mind with regards to UI layer
  defining those constants. Let me know!"
  - Reply (James): "I was mostly thinking about naming the params to
    something more generic/stable. I also think having the client own these
    buckets could become problematic. If we want to add/remove/reorganize
    dish types in the future, we'd need coordinated app updates across
    platforms instead of being able to adjust the grouping server-side."
  - Reply (Wally): "Can this be a DC and we can abstract out to models if
    this experiment wins? label → query filters (i want to reduce as much
    scope as possible)…"
  - *RESOLVED:* DC-backed mapping shipped (BE-7819). See *Occasion Filters*
    above.

- =Request Body:= (Favorite an Item) :: James Chen — "is =item_type=
  necessary if the request is already distinguished by =pairing_id= vs
  =product_id=? If we do have both, what happens if the values are
  mismatched?"
  - Reply (Andrew): "Is there a reason clients can't continue using the
    same =POST /api/v2/customers/{customer_id}/favorite_pairings/= and the
    product version pattern? Clients need the synthesized item dict from
    the GET response?"
  - Reply (Wally): "FWIW, migrating over to the V3 endpoint isn't high on
    my priority list for the MVP if the V2 endpoint works for the
    experiment."
  - Reply (James): "@Andrew Kim clients can continue to use v2. For the
    MVP, we're also going to stick with V2 and migrate to V3 at a later
    point."
  - *RESOLVED:* V3 surface is read-only for MVP; writes stay on V2.

- =Position= :: Wally — "I am more in favor of not using =position= and
  instead, use the order returned from the BE based on any sort/filter
  query parameters used by clients."

- =Not stable across requests= :: James Chen — "Is it stable across pages?"
  - Reply (Wally): "cc @Colin Powell if we provide a default sort, then this
    should be stable right?"
  - *RESOLVED:* Position is now the offset-aware global rank in the sorted
    result set. Stable across pages for a given sort.

- =Phase 2= :: Wally — "AFAIK, creation of a cookbook and sharing (publically)
  the user's cookbook is part of phase 1."
  - Reply (Colin): originally proxy MVP scope. If sharing cookbooks is
    Phase 1 too, prefer to actually modify the Cookbook model rather than
    proxy. @James Chen — what do you think?
  - Reply (Wally): proxy is to avoid lengthy migration + dual write while
    experiment runs. Once experiment done and rolling out to everyone,
    original (model-mod) approach is better. Maybe warrants live call.
  - Reply (Wally, separate): can we add a different "personal" type to the
    existing cookbook infrastructure for user-generated cookbooks?

- =/cookbooks/favorites/= :: Wally — "For the future: Does this return all
  favorites from all cookbooks or does it accept some sort of cookbook ID?"

- =Overview= :: Wally — "Is there documentation around supporting publicly
  accessible user-generated cookbooks?"

- =Meal-category filtering is UI-driven. The new endpoint accepts a dish_type
  query parameter (CSV of DishType slugs). Clients map their bucket labels
  ("Breakfast", "Lunch + Dinner", "Snacks & More") to slug lists. No
  server-side mapping table.= :: Wally — "if a dish_type param is provided,
  would =breakfast= filter show products like yogurt, pancake?"
  - *RESOLVED (partial):* For Lunch+Dinner, server-side mapping (DC) +
    hybrid Tag filter handles ingredient and RTE products. Breakfast/Snacks
    remain open — see *Coverage gap* and Open Questions.

- =favorites_v3_enabled= :: Wally — "hmm what is this used for?"
  - Reply (James): "Is this meant for the clients? Unless the BE needs this,
    we typically create our dcs under the prefix =ios.= and =android.=. We
    also don't always have feature gates for v3 migration."
  - *RESOLVED:* DC dropped. Cutover is purely client-side via app release;
    no server-side gate needed.

- =Response:= (Retrieve Personal Favorites Cookbook) :: Wally — "is this the
  same shape as other cookbook APIs? if so, we can probably leave it the
  same, if not, we could optionally use v3 pairings/products endpoint for
  hydration to keep the payload small."
  - Reply (Wally): "+1 I expect this to only return information specific
    to cookbooks and omit anything we can get from hydrating on the
    client."
  - *RESOLVED:* Response now mirrors =CookbookSerializer= top-level fields.
    Item payload is minimal (=id=, =item_type=, =position=, =pairing_id=,
    =product_id=) — clients hydrate via v3 pairing/product endpoints.

- =Favorite an Item= :: Wally — "does it make sense to continue using the
  bookmark endpoints for favoriting and unfavoriting to decrease scope?"
  - *RESOLVED:* Yes — V2 endpoints stay for writes in MVP.

- =fields= (Phase 2 model) :: Andrew Kim — "How is =owner= to be used
  differently than =author=?"
  - Reply (Colin): author was how a cookbook got associated with an HR
    customer. But for sharing cookbooks, customers probably don't need a
    whole "author" profile, so add an owner FK to customer and deprecate
    the Author.user.

- =no data migration required= :: Andrew Kim — "You're probably not going to
  be able to add a non-nullable field here because it's not
  backward-compatible. You'll have to make a nullable field and existing
  cookbooks won't be backfilled automatically with =CURATED=."

- =Products are unaffected by this filter= :: Andrew Kim — "What about
  ready-to-eat/heat&eat meals, which are products? These have dish types
  via tags. On that note, should we be filtering based on dish type tags
  instead of the dishtype FK?"
  - *RESOLVED:* Hybrid filter shipped (BE-7817 scope expansion). Product
    filter ORs =Product.dish_types__slug__in= with daypart Tag membership
    (=Tag.ID.LUNCH_*= / =Tag.ID.DINNER_*=) so RTE meals surface under
    Lunch+Dinner. See *Services* and *Occasion Filters* above.

- =Response:= (Retrieve Personal Favorites Cookbook, second comment) ::
  Andrew Kim — "I don't think it's v3-esque to include the item details.
  Clients should be passing the pairing/product IDs to the v3
  pairing/product cached endpoints to fetch whatever pairing/product
  details they need. Also, do we need =position= or =created_at=? Also,
  not sure about the composite pairing/product IDs pattern. Is that
  better/easier for clients to delete a favorite rather than passing
  something like =pairing_id=x= or =product_id=y=?"
  - *RESOLVED (partial):* Item payload trimmed to minimal IDs; no nested
    pairing/product details. =position= retained as offset-aware global
    rank. =created_at= dropped from the item; ordering happens on the
    through-row's =create_date= server-side. Composite IDs kept since
    there's no real PK for the synthesized item — through-row PKs overlap
    across tables.

- =Unfavorite an Item= :: Andrew Kim — "Same question as above for
  favoriting an item. Clients could keep using =DELETE
  /api/v2/customers/{customer_id}/favorite_pairings/{pairing_id}/= and
  product one?"
  - *RESOLVED:* Yes — V2 endpoints stay for writes in MVP.