- ID
- 28d9be2d-13d8-43f7-9cea-6e5cbac9a25f
BE-7389 Spike: Spec out Django models and APIs for Cookbooks / Collections app
- source :: https://hungryroot.atlassian.net/browse/BE-7389
- tags :: Hungryroot API Project
- epic :: EP-411 Eng Parking Lot
- sprint :: HR BE Sprint 106
- status :: Status - Complete
Design doc: HR Technical Design Doc: Curated Collections
Tasks
DONE Research how we build out design documents
- ID
- 621147dc-a33f-5ddd-b480-cfc21e42f45d
DONE Finish writing up TDD
- ID
- e608ceec-3155-feaa-1562-311572df82d1
DONE Update TDD doc after talking with Stephen
- ID
- e1369519-71e4-fb6e-df90-26d5e995e4b8
DONE Review comments on Cookbook TDD
- ID
- 51c56c39-78a1-800a-19fc-e9196f694e65
DONE Final clean up of Cookbook TDD
- ID
- cfb68904-675c-81a4-cc98-28044938ae1c
DONE Cut tickets for Cookbook MVP
- ID
- a154834e-2ad5-98f2-2e3c-b0a5c6c2ee18
- Note taken on
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]]
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