Org Web Adapter

Editing hungryroot/jira/be_7389_spike_spec_out_django_models_and_apis_for_cookbooks_collections_app.org

:PROPERTIES:
:ID:       28d9be2d-13d8-43f7-9cea-6e5cbac9a25f
:END:
#+title: BE-7389 Spike: Spec out Django models and APIs for Cookbooks / Collections app

- source :: https://hungryroot.atlassian.net/browse/BE-7389
- tags   :: [[id:3a477c02-e26d-40f7-a719-0aa1cd169dd8][Hungryroot API Project]] 
- epic   :: [[id:86327fb4-0f66-4bc6-9068-c414cea77042][EP-411 Eng Parking Lot]]
- sprint :: [[id:9821b605-4d59-432e-b15d-95999d25cc39][HR BE Sprint 106]] 
- status :: [[id:4d41d978-e56f-45c1-88d1-e2c76510972e][Status - Complete]]
  
Design doc: [[id:7eae8a7e-9211-4ce2-8bf2-6d9636882b4b][HR Technical Design Doc: Curated Collections]]

* Tasks
** DONE Research how we build out design documents :work:research:hungryroot:ep411:be7389:sprint106:
:PROPERTIES:
:ID:       621147dc-a33f-5ddd-b480-cfc21e42f45d
:END:
** DONE Finish writing up TDD :work:docs:hungryroot:ep411:be7389:sprint106:
:PROPERTIES:
:ID:       e608ceec-3155-feaa-1562-311572df82d1
:END:
** DONE Update TDD doc after talking with Stephen :work:docs:hungryroot:be7389:sprint106:ep411:
:PROPERTIES:
:ID:       e1369519-71e4-fb6e-df90-26d5e995e4b8
:END:
** DONE Review comments on Cookbook TDD :work:docs:hungryroot:be7389:sprint106:ep411:
:PROPERTIES:
:ID:       51c56c39-78a1-800a-19fc-e9196f694e65
:END:

** DONE Final clean up of Cookbook TDD :work:docs:hungryroot:be7389:sprint106:ep411:
:PROPERTIES:
:ID:       cfb68904-675c-81a4-cc98-28044938ae1c
:END:
** DONE Cut tickets for Cookbook MVP :work:jira:hungryroot:project:be7389:ep411:sprint106:
:PROPERTIES:
:ID:       a154834e-2ad5-98f2-2e3c-b0a5c6c2ee18
:END:
<2026-03-30 Mon>

- Note taken on [2026-03-30 Mon 12:43]

Not the craziest work, but I created three tickets for a total of four story
  points to stub out the models, add a service layer for upsert and wire the
  whole thing up with views and serializers.

* Description
[[https://docs.google.com/document/d/15UDQTZtmtLImJcf0CjWRDratVeIINBQvAb5-p6BYFuw/edit?tab=t.kupfnodp89p8][Cookbooks & IA]]
[[https://docs.google.com/document/d/1xRbtnRQ7KY3sTrSXKZj0Tw2-Q1nFK9ZdWkPdZtFBf-k/edit?tab=t.kupfnodp89p8#heading=h.7hf0k9bav2ye][Exp xxx: Hungryroot.com Cookbook MVP]]
[[https://www.figma.com/proto/obNmvN39MrR8JNr55B8cd4/Brand-lander-test?page-id=0%3A1&node-id=54-6557&viewport=-5288%2C1747%2C0.13&t=OwIy3qLCgsG9bWbM-9&scaling=scale-down&content-scaling=fixed&starting-point-node-id=54%3A6557&show-proto-sidebar=1][Figma]]

** Context

Our homepage and funnel currently rely too heavily on describing the service
rather than demonstrating it. Key survey findings from cart abandoners:

50% wanted to explore meals and food options before committing

52% of those prospects wanted to verify the food fit their dietary needs and
preferences

35% weren't sure if Hungryroot offered the type of food or meals they were
looking for

Only 29% felt the experience was personalized to them

By enabling prospective customers to discover relevant, personalized
collections, we have an opportunity to give them a tangible sense of what
Hungryroot offers and the confidence they need to commit.

** High-Level Solution

Showcase collections of recipes/products ("Cookbooks")

Leverage key aspects of our service from the existing homepage and integrate
them into a new homepage so customers understand how it works

Customers go through the existing funnel from the new homepage

A Cookbook is a curated collection of recipes and products

** Spike Goals

Design and document the Django models, APIs, and app structure required to stand
up a new cookbooks (or collections) Django app. This is a spike -- the
deliverable is a technical spec, not working code.

*** 1. Django Models

Define the core models: Collection (aka Cookbook), membership/association models
linking to recipes and products

Consider metadata fields: title, slug, description, hero image, display
ordering, active/inactive status, dietary tags

Consider whether collections are manually curated, rule-based (dynamic), or a
hybrid

Plan for personalization: how do we surface the right collections for a given
customer's dietary profile?

Identify relationships to existing models (Product, recipe models, Customer,
dietary preference models)

Consider ordering and ranking of items within a collection

*** 2. API Design

List collections (public, unauthenticated -- for homepage/funnel)

Retrieve a single collection with its items

Filter/search collections by dietary tags, category, etc.

Admin/internal endpoints for CRUD on collections and their memberships

Pagination strategy for collection items

Caching strategy (these will be high-traffic, public-facing endpoints)

*** 3. App Structure

Follow existing Django app creation conventions (see
.cursor/rules/django-app-creation.mdc)

Service-first architecture: thin views, business logic in services

Identify any new dependencies or integrations needed

*** 4. Open Questions to Resolve

Naming: cookbooks vs collections vs something else?

Should collections support mixed content (recipes + products) or be typed?

How do we handle collection versioning or seasonal rotation?

What is the personalization strategy -- tag-based filtering, ML-driven ranking,
or editorial curation?

How does this integrate with the existing funnel flow?

Do we need a separate CMS/admin interface or will Django admin suffice
initially?

** Acceptance Criteria

- [ ] Technical spec document (Confluence or PR) covering models, APIs, and app structure
 - [ ] ER diagram or model relationship diagram
 - [ ] API contract (endpoint paths, request/response shapes)
 - [ ] Identified dependencies on existing models and services
 - [ ] List of open questions resolved or escalated
 - [ ] Estimated story points for implementation work