Org Web Adapter

Editing hungryroot/brand/tdd-canonical-brand-entity.org

#+title: TDD: Canonical Brand Entity

* Overview
:PROPERTIES:
:CUSTOM_ID: overview
:END:
Promote brand from a denormalized text field on =Product= to a canonical =Brand= entity that discovery, search, merchandising, and client surfaces build against. A new standalone =brands= app carries the model (slug, display name, marketing copy, visual assets, activation state); a =Product → Brand= FK replaces string reads via an expand → migrate → contract rollout with read-fallback to the legacy field throughout the transition.

=Product.brand_name= is today a free-text =CharField(max_length=50, null=True, blank=True)= (=app/models/product.py:105=) --- the platform's only brand representation. It is searchable and boosted in both Algolia and OpenSearch, baked into the semantic-embedding text, and drives business logic by raw string compare.

*Status:* =DRAFT= --- Epic [[https://hungryroot.atlassian.net/browse/EP-667][EP-667]]

*Prior art:* supersedes =first-class-brand-model-plan.org= (same directory). Key change from that plan: single =ForeignKey= instead of M2M + =ProductBrand= through model --- current data is strictly one brand per product, and that plan itself flagged FK as the simpler choice pending cardinality confirmation. See Alternatives Considered.

** Problem
:PROPERTIES:
:CUSTOM_ID: problem
:END:
Brand and growth teams want brand-led merchandising and discovery experiences (brand pages, brand-filtered browse, brand-aware ranking). Today:

- No canonical identity --- spelling variants ("Banza", "banza", "BANZA ") read as distinct brands; no stable ID, no shared assets, dirty cardinality
- Only edit path is per-product Django admin --- =brand_name= isn't even in the =BulkProductUpdate._TEXT_FIELDS= allowlist, so there is no bulk tooling and no place for brand-level metadata (logo, description, activation)
- Business logic keys off the raw string --- =Product.is_third_party= compares =brand_name.lower() != "hungryroot"= (=app/models/product.py:430=); a hardcoded Banza name override lives at =app/services/api/product.py:210=
- Search leans on the free text --- =brand_name^2= multi-match boost plus a 6.0 exact-match =constant_score= in OpenSearch, =searchableAttributes= position 2 in Algolia --- but there is no brand facet or filter anywhere
- Every new brand-flavored surface requires a one-off integration against the string

** People
:PROPERTIES:
:CUSTOM_ID: people
:END:
| Role             | Name                                                                                                                                                                                              |
|------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Technical Author | Colin Powell                                                                                                                                                                                      |
| Jira             | [[https://hungryroot.atlassian.net/browse/EP-667][EP-667]] (stories [[https://hungryroot.atlassian.net/browse/BE-8109][BE-8109]] -- [[https://hungryroot.atlassian.net/browse/BE-8118][BE-8118]]) |

* Design
:PROPERTIES:
:CUSTOM_ID: design
:END:
** Canonical Brand Model
:PROPERTIES:
:CUSTOM_ID: canonical-brand-model
:END:
New standalone =brands= Django app (mirrors =bonus_bites= skeleton). Model mirrors =DishType= for slug/images/description and =CookbookAuthor= for =is_active=:

| Field            | Type                                                              | Purpose                                                                                 |
|------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------|
| =name=           | =CharField(max_length=200)=                                       | Canonical display name                                                                  |
| =slug=           | =SlugField(max_length=100, unique=True)=                          | Stable URL identity; auto-generated in =clean()=+=save()=; =UniqueConstraint= in =Meta= |
| =description=    | =TextField(blank=True)=                                           | Marketing copy                                                                          |
| =logo_image=     | =FileField(upload_to=unique_upload_path, storage=public_storage)= | Admin-uploaded; served via CloudFront (=build_cdn_url=)                                 |
| =hero_image=     | =FileField(...)= (same pattern)                                   | Brand-page hero asset                                                                   |
| =sort_order=     | =SmallIntegerField(default=0)=                                    | Merchandising order                                                                     |
| =is_active=      | =BooleanField(default=False)=                                     | Activation state; inactive brands hidden from client surfaces                           |
| =is_first_party= | =BooleanField(default=False)=                                     | Replaces the =brand_name.lower() != "hungryroot"= string compare                        |

=BrandAdmin= (SimpleHistoryAdmin) is the ops management surface: create/edit brands, upload logos, toggle activation --- replacing per-product free-text edits.

** Product Relationship
:PROPERTIES:
:CUSTOM_ID: product-relationship
:END:
#+begin_src python
# app/models/product.py (proposed)
brand = ForeignKey("brands.Brand", null=True, blank=True, on_delete=PROTECT, related_name="products")
#+end_src

- Cardinality: one brand per product (FK, not M2M) --- matches current data shape
- =on_delete=PROTECT=: a brand with live products cannot be deleted; deactivate via =is_active= instead
- Nullable during the transition; flipped to non-null in the contract phase after backfill is verified

** Backfill & Normalization
:PROPERTIES:
:CUSTOM_ID: backfill--normalization
:END:
Backfill collapses =brand_name= variants to canonical rows via =get_or_create= on a normalized name (rule finalized in BE-8109; baseline: lowercase, strip, collapse internal whitespace):

#+begin_src python
# app/migrations/XXXX_backfill_product_brand.py (proposed sketch, follows 0621 precedent)
def backfill_brands(apps, _schema_editor):
    Product = apps.get_model("app", "Product")
    Brand = apps.get_model("brands", "Brand")
    for product in Product.objects.exclude(brand_name__isnull=True).exclude(brand_name=""):
        normalized = normalize_brand_name(product.brand_name)
        brand, _ = Brand.objects.get_or_create(
            slug=slugify(normalized),
            defaults={"name": normalized.title(), "is_first_party": normalized == "hungryroot"},
        )
        product.brand = brand
        product.save(update_fields=["brand"])
#+end_src

** Read-Fallback During Transition
:PROPERTIES:
:CUSTOM_ID: read-fallback-during-transition
:END:
Every canonical read falls back to the legacy field while FKs may be null:

#+begin_src python
# Product (proposed)
@property
def canonical_brand_name(self) -> str | None:
    return self.brand.name if self.brand_id else self.brand_name
#+end_src

Both search indexes and all serializers read through this fallback until the contract phase, so search/discovery quality is preserved even mid-backfill.

** Search Indexing
:PROPERTIES:
:CUSTOM_ID: search-indexing
:END:
| Index                                                        | Change                                                                                                                                                                                                                                                            |
|--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| OpenSearch =ProductSearch= (=hrsearch/search.py=)            | Add =brand_id= as =KeywordField= (facetable/filterable) + canonical brand name with fallback. Semantic-embedding template (=hrsearch/utils.py= → =product_search.html=) switches to canonical brand; nightly =rebuild_product_search_index= picks up the mapping. |
| Algolia =ProductIndex= (=app/index.py=)                      | Canonical brand field with fallback; add brand to =attributesForFaceting= --- the first brand facet. Settings applied via existing =post_migrate= receiver.                                                                                                       |
| Query layer (=hrsearch/open_search/query_builders/specs.py=) | Brand facet/aggregation + brand filter on =brand_id=; move =brand_name^2= and the 6.0 =product_brand_exact_boost= onto the canonical field, weights still via =SEARCH_DEFAULT_WEIGHTS= dynamic config.                                                            |

** Feature Flag
:PROPERTIES:
:CUSTOM_ID: feature-flag
:END:
| Config key                            | Type                              | Default | Purpose                                                                                                                                                                                                                              |
|---------------------------------------+-----------------------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| =api.brand_entity.serializer_enabled= | Boolean (=BoolDynamicConfigEnum=) | ="0"=   | Gates the removal of the legacy =brand_name= field from API responses (mirrors the =COOKBOOK_LIST_REMOVE_DEPRECATED_FIELDS= pattern). Nested =brand= object ships unconditionally; the flag only controls dropping the legacy field. |

** Alternatives Considered
:PROPERTIES:
:CUSTOM_ID: alternatives-considered
:END:
| Approach                                                                              | Rejected Because                                                                                                                                                                                                     |
|---------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Brand model in the =app= monolith                                                     | Standalone app gives clean ownership (CODEOWNERS), isolated migrations, and its own test/service layout; app-creation cost is 5 config files, paid once                                                              |
| Ops-curated variant→canonical mapping table                                           | Auto =get_or_create= on a normalized name covers case/whitespace variants with zero ops burden; residual near-dupes ("Ben & Jerry's" vs "Ben and Jerrys") are fixable post-hoc in =BrandAdmin= (merge = repoint FKs) |
| Enum/choices field instead of a model                                                 | Brands carry metadata (logo, copy, activation) and change at merchandising cadence --- data, not code                                                                                                                |
| M2M + =ProductBrand= through model (=is_primary=) --- the prior plan's recommendation | Current data is strictly one brand per product; M2M complicates every serializer and index for a cardinality we don't have. Revisit only if product confirms multi-brand SKUs (sub-brands, co-branding)              |
| Keep the string, add validation                                                       | Solves spelling only; no stable ID, no assets, no activation state, no brand pages                                                                                                                                   |
| Big-bang cutover (drop =brand_name= immediately)                                      | =brand_name= is embedded in the OpenSearch semantic vectors, Algolia searchable attributes, ~12 serializers, Braze/Segment events, and pick tickets --- fallback dual-read is the only safe path                     |

* Implementation
:PROPERTIES:
:CUSTOM_ID: implementation
:END:
** Files Changed
:PROPERTIES:
:CUSTOM_ID: files-changed
:END:
| File                                                                                                                                                                                 | Change                                                                  | Story   |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+---------|
| =brands/= (new app: models, admin, migrations, tests)                                                                                                                                | =Brand= model + =BrandAdmin=                                            | BE-8110 |
| =hrplatform/settings/components/common.py=, =.pre-commit-config.yaml=, =Dockerfile-seed=, =pyproject.toml=, =CODEOWNERS=                                                             | New-app registration (5 config files)                                   | BE-8110 |
| =app/models/product.py=                                                                                                                                                              | =brand= FK + =canonical_brand_name= fallback property                   | BE-8111 |
| =app/migrations/=                                                                                                                                                                    | AddField + backfill data migration                                      | BE-8111 |
| =hrsearch/search.py=, =hrsearch/utils.py=, =hrsearch/templates/hrsearch/product_search.html=                                                                                         | =brand_id= KeywordField, canonical name w/ fallback, embedding template | BE-8112 |
| =app/index.py=                                                                                                                                                                       | Algolia canonical brand field + brand facet                             | BE-8113 |
| =hrsearch/open_search/query_builders/specs.py=                                                                                                                                       | Brand facet/filter; boosts moved to canonical field                     | BE-8114 |
| =app/rest/product.py=, =app/rest/v3/product.py=, =app/rest/pairing.py=, =app/rest/pairing_swaps.py=, =discovery_home/views/v2/collection.py=, =scsort/views/foryou_products.py=, ... | Nested =brand= object; legacy field behind flag                         | BE-8115 |
| =brands/views.py= + URL conf                                                                                                                                                         | =GET /brands/=, =GET /brands/<slug>/=                                   | BE-8116 |
| =app/models/product.py:430=, =app/services/api/product.py:210=, =app/services/braze_helpers.py=, =app/services/ops/pick_ticket_service.py=, =app/rest/cart.py=                       | Move string-keyed logic to =brand.is_first_party= / brand-driven rules  | BE-8117 |
| Everything above + =app/django_admin/product_admin.py=, =app/admin/stock.py=                                                                                                         | FK non-null; remove =brand_name= everywhere                             | BE-8118 |

** Brand Model (proposed sketch)
:PROPERTIES:
:CUSTOM_ID: brand-model-proposed-sketch
:END:
#+begin_src python
# brands/models.py — proposed; mirrors DishType + CookbookAuthor patterns
class Brand(BaseModelV1):
    name = models.CharField(max_length=200)
    slug = models.SlugField(max_length=100, unique=True)
    description = models.TextField(blank=True)
    logo_image = models.FileField(upload_to=utils.unique_upload_path, storage=utils.public_storage, blank=True, null=True)
    hero_image = models.FileField(upload_to=utils.unique_upload_path, storage=utils.public_storage, blank=True, null=True)
    sort_order = models.SmallIntegerField(default=0)
    is_active = models.BooleanField(default=False)
    is_first_party = models.BooleanField(default=False)

class Meta:
        constraints = [models.UniqueConstraint(fields=["slug"], name="brand_uniq_slug")]

def clean(self) -> None:
        super().clean()
        if not self.slug:
            self.slug = slugify(self.name)

def save(self, *args, **kwargs) -> None:
        self.clean()
        super().save(*args, **kwargs)

@property
    def logo_image_url(self) -> str | None:
        return utils.build_cdn_url(self.logo_image.name if self.logo_image else "")
#+end_src

* Rollout
:PROPERTIES:
:CUSTOM_ID: rollout
:END:
- [ ] BE-8109 --- audit prod =brand_name= values; lock normalization rule (fills the data table below)
- [ ] BE-8110 --- deploy =brands= app + =BrandAdmin= (no behavior change; new empty table)
- [ ] BE-8111 --- deploy FK + backfill migration; verify cardinality diff on prod snapshot before merge
- [ ] BE-8112 / BE-8113 --- index canonical brand in OpenSearch + Algolia with fallback; confirm nightly rebuild picks up mapping; spot-check search quality pre/post
- [ ] BE-8114 --- enable brand facet/filter; move boosts to canonical field
- [ ] BE-8115 --- ship nested =brand= object in APIs (legacy field still present, flag off)
- [ ] BE-8116 --- launch =GET /brands/= + brand pages
- [ ] BE-8117 --- cut business logic over to =brand.is_first_party=
- [ ] Clients confirm migration to nested =brand= object → flip =api.brand_entity.serializer_enabled= to ="1"=
- [ ] BE-8118 --- FK non-null, remove =brand_name= from indexes/serializers/admin, =RemoveField=

* Current brand_name Data
:PROPERTIES:
:CUSTOM_ID: current-brand_name-data
:END:
/Pending the BE-8109 audit --- populate before implementation starts./

| Metric                                   | Value |
|------------------------------------------+-------|
| Products with non-empty =brand_name=     | TBD   |
| Distinct raw values                      | TBD   |
| Distinct after normalization             | TBD   |
| Variant clusters (case/whitespace dupes) | TBD   |
| First-party ("Hungryroot") share         | TBD   |

* Risks
:PROPERTIES:
:CUSTOM_ID: risks
:END:
| Risk                                                                     | Mitigation                                                                                                                                          |
|--------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------|
| Changing the embedding text forces a full OpenSearch semantic reindex    | Nightly =rebuild_product_search_index= already rebuilds the full index; ship the template change with the mapping change so one rebuild covers both |
| Auto-normalization mis-merges two genuinely distinct brands              | BE-8109 spot-checks the collision set before backfill; residual fixes are FK repoints in =BrandAdmin=                                               |
| Search quality regression while FKs are partially populated              | Read-fallback to legacy =brand_name= in both indexes and all serializers; legacy field untouched until BE-8118                                      |
| =on_delete=PROTECT= blocks brand deletion with live products             | Intentional --- deactivate via =is_active=; prevents orphaning product data                                                                         |
| 5-min DynamicConfig cache = up to 5-min flag-flip lag                    | Same SLA as all existing flags; acceptable                                                                                                          |
| =RemoveField brand_name= also alters the large =HistoricalProduct= table | Standard simple-history migration; run in a low-traffic window like migration 0696 did                                                              |
| Clients break when legacy =brand_name= is dropped from responses         | Field removal is flag-gated per the cookbook deprecated-fields precedent; flip only after client confirmation, roll back in ≤5 min                  |