Shopping Lists and Shop a List
Audience: User, Org Admin, Developer, Support Related: Meal Planner · Kitchen Inventory · Household and External Shopping · Data Retention
Shopping Lists can be created from recipes, selected meal-plan scope, or manual items. Ingredient scaling, normalization, source provenance, recipe multipliers, departments, inventory filtering, ownership, and list lifecycle are preserved through editing and Shop a List.
Shop a List provides recipe, department, and flat grouping, quick manual additions, undo behavior, and completion handling. Completed lists are retained or purged according to the configured policy.
This document captures the stabilized shopping-list architecture and UI split after the Shop a List, Edit Shopping List, Kitchen Inventory, and department-management improvements.
Workflow split
Blackcap Pi intentionally separates shopping-list work into three surfaces.
| Surface | Purpose | Primary users |
|---|---|---|
| Shopping Lists | Manage saved lists, active/completed state, print, reopen, and entry points. | Admin users. |
| Edit Shopping List | Compose/repair a list: recipes, multipliers, manual additions, preview, save, rebuild. | Admin users. |
| Shop a List | Execute the list while shopping: checkoff, inventory filter, add item, department reassignment, complete. | Admin and Mobile users. |
The Mobile execution page should be called Shop a List, not simply Shopping.
Shopping-list lifecycle
- Lists can be created from the Recipe Cart or manually.
- After Recipe Cart → Shopping List creation commits successfully, Blackcap clears that organization/user cart through the normal cart service. If Shopping List creation or cart persistence fails, the transaction rolls back and the original recipes/multipliers remain available for retry. Unrelated Shopping List creation does not clear the Recipe Cart.
- Recipe Library shows a short-lived, normal Blackcap Shopping List Created confirmation after creation. The confirmation includes the associated recipes with the same constrained multiplier behavior used by Recipe Cart, the generated shopping-list ingredients, and compact Shop This List / Edit / Print actions. Multiplier changes save immediately and the returned Shopping List re-renders the ingredients without a page refresh. The Recipe Cart itself immediately renders its empty state rather than retaining a stale copy of the converted recipes.
- Recipe-created lists receive consumer-friendly smart names based on list date and recipes.
- Empty manual lists require a user-provided name.
- One list can be active at a time for an organization.
- Completed lists are excluded from Shop a List and Edit Shopping List selectors.
- Completing an active list clears the active-list state.
- Completed lists can be reopened from Shopping Lists.
- Completed lists cannot be made active until reopened.
Meal Planner as a shopping-list source
Meal Planner is another composition source for Shopping Lists. It does not create a parallel shopping system.
When a shopping list is created from Meal Planner:
- recipe-backed meal entries contribute ingredients using the meal-plan recipe multiplier;
- manual meal items contribute ingredient-style candidates when marked for shopping inclusion;
- uncanonicalized manual meal items remain reviewable just like unresolved recipe ingredients;
- the resulting list is still edited in Edit Shopping List and executed in Shop a List;
- Kitchen Inventory / On Hand behavior remains in the shopping-list execution layer.
If no specific days/slots are selected in Meal Planner, Create Shopping List defaults to the current configured/working week rather than a whole month view.
Direct Component Recipes in Shopping List creation
Shopping List creation uses the same direct-Component discovery and quantity planner as Let’s Cook. Before generating recipe-derived shopping rows, Blackcap can identify a parent ingredient whose structured name exactly matches an active same-organization Component recipe. For one dated Meal, Blackcap first reuses any provisional Component setting already saved with that Meal. It asks for Component choices only when shopping actually needs a decision that is still unresolved. When it asks, it uses the same rich Component Recipe card as Let’s Cook rather than a separate shopping-only control. Component expansion is one level only; ingredients inside a Component are never expanded as additional Components.
The preflight labels each card Make Component from scratch for and shows the parent recipe or recipes that need it. Parent context stays compact: a small thumbnail plus recipe name, one parent per row when several selected recipes use the same Component. The Component recipe's normal time/cleanup/effort pills remain on the left side of that context so the extra parent information has minimal UI impact.
For Make From Scratch:
- Apply each parent recipe multiplier to its Component ingredient requirement.
- Aggregate repeated references within a parent and the same Component across all selected parent recipes using safe compatible-unit conversion.
- Calculate
required amount / Component 1x yield. - Apply the normal recipe multiplier/discrete-ingredient rules and choose the smallest valid multiplier that still produces enough.
- Add the Component Recipe once as a normal Shopping recipe source using that multiplier.
- Scale its ingredients through the existing recipe → normalization → consolidation pipeline.
- Suppress the finished Component ingredient from the parent shopping requirements.
When Make from scratch is unchecked, Blackcap does not add the Component recipe. The parent's normally scaled finished-Component ingredient behaves exactly like an ordinary pre-Component-feature shopping ingredient and remains on its own Shopping List row.
A missing structured yield or incompatible unit never causes an unsafe conversion. The preflight instead keeps the Component relationship visible and uses a manually selected multiplier. Duplicate same-name Component recipes remain unresolved until the user chooses the specific recipe; the server then recalculates the recommendation from that recipe's yield and ingredient constraints before creation.
Component source multipliers and make/keep decisions are persisted with the Shopping List and reapplied during both an explicit rebuild and the automatic recipe-derived refresh used by Shop a List / Shop With. Automatic refresh must rebuild from the parent sources and then re-expand the saved Component choices; it must never restore the finished Component ingredient to the parent while the Component is being made from scratch. Lists affected by the older refresh behavior can recover a lost Make From Scratch choice when the matching Recipe Type=Component recipe is still present on the list. When the selection represents one dated Meal, the explicit choices are also saved as that Meal's provisional Component settings. A multiplier equal to Blackcap's current recommendation stays derived rather than becoming a fixed override, so it follows later parent-Recipe multiplier changes. The user can still change the decision at Let’s Cook. The Component's ingredient rows continue through normal consolidation, Have It, department, and Track Kitchen Inventory behavior. Blackcap does not automatically create inventory for excess Component output.
Smart list names
Smart names should be friendly for household users rather than developer-style timestamps.
Preferred format:
May 22, 2026 · Cheeseburger Pie +1 Recipe
If the same date/recipe/count combination already exists, append a suffix:
May 22, 2026 · Cheeseburger Pie +1 Recipe -1
Custom/manual names should be preserved. Generic placeholders such as Shopping List should not be used for newly created blank lists.
Edit Shopping List rules
Edit Shopping List is a composition page.
Supported actions:
- select an editable non-completed list;
- adjust recipe multipliers using fraction controls;
- remove recipes from the list;
- add/remove manual shopping items;
- save changes;
- rebuild recipe-derived rows when permitted;
- print or cancel back to the previous page.
Important boundaries:
- Recipe-derived ingredient rows are preview-only here.
- Checkoff happens in Shop a List.
- Manual-verification or recipe-derived loose rows should not appear as removable manual items.
- Save should rebuild recipe-derived quantities from the current recipe multipliers.
- Manual additions should be preserved across save/rebuild.
- Unsaved-change warnings should appear before switching lists or leaving the page.
- Completed lists should be reopened from Shopping Lists before editing.
Data Admin, Org Admin, and System Admin users can use Rebuild. The Rebuild action is intentionally role-restricted because it rewrites generated list rows from source recipes/multipliers/manual items.
Shop a List rules
Shop a List is the execution page.
Supported actions:
- check/uncheck items with the existing fast normal tap/click path;
- filter All items / On hand / Need to shop;
- group by Recipe, Department, or None;
- add a manual item without leaving the page;
- remove manual items with undo;
- change department assignments;
- optionally use ║█║▌║║ Scan Product to associate the exact purchased Product;
- complete the list.
Shop a List renders a purchase-facing ingredient label rather than repeating cook-time preparation instructions. Quantity/unit are preserved, but unambiguous preparation/state/source wording is omitted: 4 poached pears halved and cored displays as 4 pears, 1 lb red potatoes cut into 1-inch chunks displays as 1 lb red potatoes, melted butter displays as butter, large eggs at room temperature displays as large eggs, 1 recipe homemade pie crust displays as 1 pie crust, and 1 cup apricot jam heated and strained displays as 1 cup apricot jam. Quantity is preserved even for older/consolidated rows whose top-level display contains only the ingredient name; for example an item stored as display=all-purpose flour, quantity=3, unit=tbsp still renders as 3 tbsp all-purpose flour, and Blackcap reuses an available single-source original such as 3 tablespoons all-purpose flour when possible. This is presentation-only; the stored recipe/shopping source text is retained for recipe provenance and cooking. Meaningful purchasable specificity is preserved, so red potatoes and all-purpose flour are not broadened to generic potatoes or flour on the shopping execution surfaces.
Ingredient identity is normalized to singular independently from the natural quantity-bearing display text. Blackcap uses LemmInflect's dictionary-backed English noun lemmatizer and verifies that a changed form is a recognized plural noun form; out-of-vocabulary rule guessing is disabled. Examples include eggs -> canonical egg, pears -> pear, red potatoes -> red potato, berries -> berry, and leaves -> leaf. Already-singular or mass-food names such as asparagus, molasses, and couscous remain unchanged. A quantity-bearing shopping label remains grammatical (4 pears, 4 large eggs), while Kitchen Inventory identity and Shop With retailer search use the singular form (pear, large egg). Manual shopping-list additions use the same path: typing 2 eggs retains 2 eggs as the user's display text and quantity, but stores normalized ingredient eggs with canonical identity egg; both the full Edit Shopping List form and the quick Shop a List/Mobile Add Item action use this shared normalization.
When recipe quantities for the same normalized ingredient use compatible measurement units, Blackcap consolidates them through the shared measurement service before shopping. It never guesses across dimensions such as volume↔weight. The resulting purchase quantity is promoted to a practical unit by magnitude (for example tablespoons to cups). Readable exact fractions whose reduced denominator is 8 or less are preserved, including familiar thirds; only awkward fractions with a larger denominator are rounded up to the next eighth so the shopping list never understates what the recipes require. For example, 11 Tbsp butter becomes 3/4 cup butter, 13 Tbsp becomes 7/8 cup, and 15 Tbsp becomes 1 cup. Recipe source quantities remain unchanged in provenance; the rounded value is the shopping/purchase quantity used downstream by Put Away.
Mobile Shopping gestures are user-configurable. The defaults preserve current behavior: swipe left and swipe right open 🏪 Change Department, while long press opens ║█║▌║║ Scan Product.
Put Away package freshness dates
When an organization uses Full Inventory Tracking, Admin and Mobile Put Away can optionally capture or edit the freshness/expiration date on the physical Package being confirmed. The same date model is used everywhere else in Kitchen Inventory: Best Before/By, Use By, Expiration, Sell By, Freeze By, or Other; month/year or full-day precision; and an explicit No Date action. Existing Package dates are preserved when Put Away changes only storage/Product details. Expiration remains advisory and does not cause Put Away or Shopping to discard, empty, or exclude a Package automatically. Admin Shop a List exposes the same scanner as a compact row action. Starting Scan Product opens the camera immediately; after decode and Product lookup, the dialog remains open so the Product name, brand, package size/unit, barcode, and source can be reviewed or edited. Accept commits the reviewed Product and completes the normal checkoff; Retry returns directly to the camera; Cancel makes no change. Scanning is never required. Meal Planner horizontal day swipes remain navigation and are not remapped by these preferences.
Completing a list processes only checked/purchased rows. Recipe ingredients and other deterministically eligible grocery items are added to Kitchen Inventory even when no barcode was scanned. Manual Meal Items from Meal Planner are not Recipe ingredients and default to Do Not Track; they can still appear during Put Away so the user can explicitly override that choice when appropriate. A scanned purchase creates/reconciles the exact Product/Package beneath the logical item. Explicit Track/Do Not Track decisions are remembered at organization level; uncertain free-form items remain reviewable and never block Shopping completion.
When grouped by Recipe or Department, Admin and Mobile Shop a List render each group as a collapsible section. Group headers use real buttons with aria-expanded, show shopped/total counts, and preserve item state when collapsed. Admin shows one intelligent control that says Collapse All when at least one group is expanded and Expand All only when every group is collapsed. Mobile adds a sticky horizontal group strip for Recipe/Department grouping; tapping a chip expands that group if needed, marks the chip active, and scrolls to the group header. The chip/header counts use the intuitive shopped/total direction, such as 3/7 shopped.
Rapid checkoff persistence
Rapid Shop a List checkoffs use an optimistic, single-flight queue. The browser keeps the latest desired checked state per item and coalesces additional taps while a save is already in flight. Checkoff targets are stable shopping-list item_id values, not the visible row index; section/index are retained only as a legacy fallback. This matters because checked rows can move after sorting, grouping, household-list inclusion, or duplicate consolidation.
The server applies the payload with the shopping-list DB service atomic mutation helper, resolves refs by item_id first, reloads the affected refs, verifies that the requested state persisted, and retries once before returning an error. If a coalesced save still fails, the browser retries still-current rows individually and only reverts rows that actually fail.
This pattern avoids launching many overlapping full-list writes, and it avoids targeting the wrong row after normalization/sorting. The route and browser code stay database-backend neutral; SQLite and PostgreSQL locking differences belong behind the DB service boundary.
Shop With extension behavior
The Chrome extension Shop With helper uses the same organization-scoped shopping-list state as Admin/Mobile Shop a List. It can run an assisted session for enabled providers such as Shipt, Target/Walmart-style providers, and Amazon.
Completing Shop With uses the same inventory-completion boundary as Shop a List: checked/purchased eligible items are added to Kitchen Inventory immediately when the Blackcap Shopping List is completed, and the completed list is persisted with its Put Away-required state before the Shop With session closes. Put Away does not create the purchase later; it only enriches/reconciles the already-created logical item/package with exact Product identity and storage location.
Session rules:
- provider and store selection are scoped to the extension token owner’s organization;
- providers can expose store modes or a free-form store text field;
- Shipt supports free-form store text with common-store suggestions, and a blank store falls back to the provider default such as
stores; - the selected provider/store stays with the active Shop With session until the session is completed, reset, or changed by the user;
- shopping credentials are not stored by Blackcap; assisted shopping relies on the user’s active browser session with the retailer.
Execution rows are consolidated before they are sent to the extension. Shop With uses the same preparation-free purchase identity as Shop a List, with singular noun identity for matching and retailer search: poached pears halved and cored is shown naturally as pears when quantity/context requires it but searches as pear. Duplicate shopping-list rows with the same normalized purchase/search identity are grouped into one assisted item where safe. Matching quantities with the same unit are summed; mixed or uncertain duplicates stay grouped with a count label rather than risking a wrong quantity. The consolidated row keeps source references to all backing shopping-list item rows, so Got It, Already Have It, Review uncheck, and Reshop update every backing row consistently.
Completion behavior is intentionally different from Return behavior. Complete finishes the session, clears the extension shopping state, and closes the side shopping panel without navigating back to Blackcap. Return is the explicit action that brings the user back to Blackcap’s Shop a List page.
Put Away Purchases
After Shopping is complete, Blackcap offers 🛍️ Put Away Purchases as an optional follow-up. Shopping is already complete before Put Away begins, so the user can leave the store, drive home, wait for a delivery, and return to the work later.
Admin and Mobile have dedicated Put Away pages. Each page includes a Completed Shopping List selector so an unfinished or historical eligible completed list can be opened manually after the user gets home or a delivery arrives. Lists whose Put Away workflow has explicitly been finished are removed from the unfinished selector. Admin Shopping Lists also links eligible completed list cards directly to the Admin Put Away page, and completing Admin/Mobile Shop a List can take the user to the matching surface immediately when desired.
The Put Away navigation item is intentionally contextual: it appears only when Kitchen Inventory tracking is enabled for the active organization and at least one completed Shopping List still has Put Away pending. Finishing Put Away records that follow-up state and removes the list from the pending count; the direct Put Away page remains able to review completed lists even after the contextual menu item disappears.
Track / Do Not Track decisions and Storage Location changes save in place on both Admin and Mobile Put Away; those actions do not require a full page refresh.
The primary Put Away workflow is Scan & Put Away rather than alphabetical list traversal. Open the completed Shopping List and start Scan & Put Away, then scan whichever physical product is currently in your hand. Blackcap resolves the Product, ranks the unfinished Shopping List items, suggests the best match, and asks the user to confirm or change both the Shopping item and Kitchen Inventory storage location before Accept & Put Away. Accept reconciles the exact Product onto the purchase package that was already created when Shopping completed and marks only that Shopping item put away. In continuous mode the camera then starts again for the next physical item.
Items marked put away are removed from the active list and moved to an Already Put Away section below the Finish Put Away control. This lets the remaining list shrink in the same order the user physically empties grocery bags or a delivery, while the original per-item location/Product controls remain available as a fallback.
Put Away can:
- resolve an uncertain item as Track in Kitchen Inventory or Do Not Track;
- scan an exact Product that was not scanned in the store;
- upgrade/reconcile the generic package created at Shopping completion instead of creating duplicate stock;
- assign a storage location;
- retain the Product/package facts on the Shopping row for later support/reconciliation.
Put Away presents the logical purchased item name rather than the Recipe quantity needed to generate the Shopping List. For example, 2 tbsp sesame oil is shown as sesame oil and ⅝ cup honey as honey. Quantity requirements remain Shopping/Recipe provenance, not the identity of the pantry item being stored.
Skipping Put Away leaves valid generic inventory in place. Product-provider failure also leaves the purchase complete and usable.
Department assignment behavior
Department reassignment should improve both the current list and future lists.
- Admin: dragging a shopping row into a grocery department changes the visible group and updates the canonical department mapping.
- Mobile: long-pressing an ingredient opens a department modal. The user can select a department, add a new department, save, or cancel.
- Department resolution uses item override first, then organization canonical mapping, then platform/default mapping, then
Other / Uncategorized.
Undo behavior
Manual item deletion should not require confirmation.
Instead, supported pages show an undo toast:
- Admin Edit Shopping List.
- Admin Shop a List.
- Mobile Shop a List.
This keeps shopping fast while still protecting against accidental taps/clicks.
Persistence boundary
Shopping-list headers are handled by the shopping-list DB service/repository flow. Shopping-list item rows and item-source rows are written together through:
inky_admin/repositories/shopping_list_item_write_repository.py
That repository helper is responsible for:
- resolving the effective organization id from the sync context or parent shopping list;
- writing
shopping_list_items.organization_id; - writing
shopping_list_item_sources.organization_id; - deleting and replacing item/source rows in one place;
- dropping stale
source_recipe_ingredient_idvalues that no longer exist, avoiding foreign-key failures during legacy payload rewrites.
Routes and templates should not write directly to shopping_list_items or shopping_list_item_sources.
Admin UI layout expectations
Advanced shopping pages use the newer split-scroll pattern:
- top/header panels can scroll fully up and out of view;
- primary content panels fill the visible viewport after the headers clear;
- internal panel scrollbars stay fully visible, including the bottom/down arrow;
- panel scroll reaches the top/bottom and hands off smoothly to the page scroll;
- avoid large blank bottom whitespace by dynamically adjusting scroll range;
- treat
top: 0as valid, not as a missing value.
This pattern applies to Shop a List, Edit Shopping List, Database Admin-style pages, and similar dual-panel admin workflows.
Smoke coverage
tests/test_shopping_list_item_write_repository.py recreates the failure shape that appeared on the Pi:
- org-scoped
shopping_list_items.organization_id NOT NULL; - org-scoped
shopping_list_item_sources.organization_id NOT NULL; - foreign keys enabled;
- source attribution payloads that do not carry organization id;
- stale recipe ingredient references that should not be written.
Run the targeted smoke test with:
python3 -m unittest tests/test_shopping_list_item_write_repository.py
More information
- Household List and External Synchronization — Maintain the persistent Household List and synchronize supported external shopping-list providers.
Singular ingredient consolidation
Recipe-derived shopping items are normalized before consolidation, in this order: first remove unambiguous preparation/state wording, then singularize the remaining ingredient identity with LemmInflect, then consolidate compatible quantities. Ordering is important: 1 large eggs at room temperature is first reduced to large eggs, then singularized to large egg; it therefore combines with a separate 1 large egg row into one 2 large egg shopping item. The same preparation-then-singular sequence applies to poached pears halved and cored -> pear, red potatoes cut into 1-inch chunks -> red potato, and apricot jam heated and strained -> apricot jam.
Consolidation no longer requires identical measurement-unit text. When the normalized ingredient is the same and Blackcap's shared measurement registry says the units are safely compatible, the quantities are converted and combined before the Shopping List is saved. For example, 1 tablespoon butter (for serving, optional) and 1/3 cup butter both normalize to butter and consolidate to one 6 1/3 tbsp butter row. The serving/optional parenthetical is preparation/purpose context and is not part of the purchase identity. Conversion remains deliberately dimension-safe: volume may combine with volume and weight with weight, but Blackcap does not infer ingredient density, so 1 cup butter and 4 oz butter remain separate rather than guessing a volume-to-weight conversion. Because Put Away consumes the completed Shopping List rows, this upstream consolidation also prevents duplicate Put Away rows for safely mergeable recipe measurements.