Browse documentation

๐Ÿงญ Start Here

Blackcap Overview โœจ Blackcap Feature Catalog ๐Ÿค– AI Features ๐Ÿงฑ Technology, Administration, and Reliability Installation First Run

๐Ÿ“˜ User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

๐Ÿš€ Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

๐Ÿ› ๏ธ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

๐Ÿฝ๏ธ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation ๐Ÿช„ Adapt Recipe and ๐ŸŽฒ Variations

๐Ÿ“… Plan Meals

Meal Planner

๐Ÿ›’ Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping ๐Ÿ”— Chrome Extension Shop With

๐Ÿงบ Manage Kitchen Inventory

๐Ÿงบ Kitchen Inventory

๐Ÿ–ฅ๏ธ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

๐Ÿง‘โ€๐Ÿณ Cook with Letโ€™s Cook

๐Ÿง‘โ€๐Ÿณ Letโ€™s Cook ๐Ÿง‘โ€๐Ÿณ Letโ€™s Cook Controls and Timers

๐Ÿค– Use and Administer AI

๐Ÿค– AI in Blackcap ๐Ÿค– AI Providers and Connections ๐Ÿค– AI Seeds and Usage Support Chat

๐Ÿ”— Use the Chrome Extension

๐Ÿ”— Blackcap Chrome Extension ๐Ÿ”— Chrome Extension Recipe Capture ๐Ÿ”— Chrome Extension Shop With ๐Ÿ”— Chrome Extension Release and Privacy

๐ŸŽฎ Play Games

Games and trivia Bramble Harvest โ€” Player Guide Flavor Lab โ€” Player Guide

๐Ÿ”Œ Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

โš™๏ธ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform โ€” current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

โš ๏ธ Troubleshoot Blackcap

โš ๏ธ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting ๐Ÿค– AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

๐Ÿงบ Kitchen Inventory

Audience: User, Org Admin, Developer, Support Related: Shopping Lists ยท Household and External Shopping ยท Data Retention

Kitchen Inventory tracks organization-scoped household items by canonical identity, grocery department, storage location, and Have It state. Active-item uniqueness prevents duplicate logical inventory records while allowing archived items to be restored.

Inventory filters shopping workflows but does not replace the Shopping List lifecycle. Archive, recently deleted, restore, purge, permission, and dependency behavior are documented here.

This document describes the current Kitchen Inventory and grocery-department model for Blackcap Pi, plus the Shop a List behaviors that use it.

Product language

Use these names consistently in the UI and documentation:

Name Meaning
Shopping Lists The saved list records created from recipes and/or manual items.
Edit Shopping List The Admin composition page for recipes, multipliers, manual items, preview, save, and rebuild.
Shop a List The Admin and Mobile execution experience for checking items off in the store.
Kitchen Inventory The household inventory list that tracks whether an item is on hand.
Grocery Department Where an item is found in the store, such as Dairy or Produce.
Storage Location Where the item lives at home, such as Refrigerator, Freezer, Pantry, or Spices.

Use On hand as the friendly state for inventory items and for shopping-list rows that Blackcap believes are already available at home.

Core concepts

Grocery department and storage location are intentionally separate.

Concept Example Used for
Grocery department Dairy Shop a List grouping and in-store navigation.
Storage location Refrigerator Kitchen Inventory organization.
Canonical item milk Normalized matching across recipes, shopping rows, and inventory.
Shopping item 1 cup milk A row in a specific shopping list.
Inventory item Milk, on hand in Refrigerator Household availability tracking.
Product Organic Valley Whole Milk, 1 gal Optional exact retail identity beneath a logical inventory item.
Physical package One owned gallon carton Durable quantity/state for a particular container.
Inventory activity Letโ€™s Cook ยท Milk ยท โˆ’1 cup Recent explanation of quantity changes; summarized before purge.

Organization inventory tracking mode

When Track Kitchen Inventory is enabled, each organization chooses one of two detail levels from both Organization surfaces:

  • Full Inventory Tracking โ€” logical inventory items plus exact Products, physical Packages, quantity/fullness, Product scanning, Put Away, inventory-photo/forecast tooling, and quantity-aware Letโ€™s Cook consumption. Existing organizations default to this mode for backward compatibility.
  • On Hand Only โ€” logical Kitchen Inventory identity and On Hand / Not On Hand state only. Product/package quantity controls, Product scanning, Put Away, and quantity/photo forecasting workflows are not offered. Shopping completion marks eligible checked items On Hand without creating Products or Packages. Because there is no Put Away review surface in this mode, otherwise unresolved grocery/manual shopping items default to the logical On Hand model; explicit or remembered Do Not Track decisions still win.

Changing the mode does not delete historical Product/Package records. While On Hand Only is selected, those records are not used by normal shopping/cooking inventory flows.

Physical package freshness / expiration dates

Full Inventory Tracking can optionally record one freshness/expiration date on each physical Package. The date belongs to the Package rather than the logical Kitchen Inventory item or retained Product, so two cartons of the same Product can carry different dates. Supported semantic types are Best Before / Best By, Use By, Expiration, Sell By, Freeze By, and Other with a short custom label. Opened, packed, and manufactured dates are intentionally outside this feature.

A Package date may have month/year precision or a complete day/month/year value. Month/year is stored without inventing a day; expiration calculations treat it as valid through the final calendar day of that month. Calculations use the organization's configured timezone and the organization setting Expiring Soon Warning (7 days by default, configurable from 1โ€“365 days). The derived Package states are No Date, Current, Expiring Soon, and Expired. Changing the warning threshold changes derived status immediately; no warning state is persisted.

Expiration is informational only. An expired Package remains on hand, remains in quantity calculations, and remains available to Shopping/Letโ€™s Cook until the user explicitly marks it empty, discarded, or otherwise changes Inventory state. Package dates can be entered or changed from Package details, manual Package creation, barcode acceptance, Put Away, and Product Photo Review. Unrelated Product metadata edits preserve an existing Package date; removing one requires the explicit No Date action.

When Full Inventory Tracking creates a new physical Package without a printed/manual freshness date, Blackcap can consult the editable platform USDA FoodKeeper Shelf Life catalog and create an Estimated Best By date. FoodKeeper is a planning aid, not an expiration guarantee: Blackcap never changes whether a Package is on hand and never invents a date when the catalog or storage context is not specific enough.

How FoodKeeper estimation works

Blackcap evaluates a new physical Package in this order:

  1. An explicit Package date always wins. If Put Away, manual Package creation, barcode/Product review, or another intake flow already supplies a freshness/expiration date, FoodKeeper is not consulted for that Package.
  2. Resolve the logical ingredient. Blackcap starts with the Kitchen Inventory item's canonical name, falling back to its display name, and normalizes it through the shared ingredient canonicalization rules.
  3. Match one active FoodKeeper profile. Exact canonical-key matches are preferred over alias matches, which are preferred over exact display-name matches. When otherwise equivalent, a System Admin-customized row wins over a current USDA row, and a current USDA row wins over the small bundled fallback catalog.
  4. Resolve the Package storage zone. Blackcap infers the FoodKeeper zone from the selected Storage Location's key/name. Freezer/frozen locations map to Freezer; refrigerator/fridge/chiller-style locations map to Refrigerator; pantry/counter/cupboard/cabinet/shelf/room/produce-style locations map to Pantry. A custom Storage Location whose key/name does not identify one of those zones intentionally receives no automatic estimate.
  5. Require a numeric duration for that zone. If the matched profile has no Pantry/Refrigerator/Freezer day value for the resolved zone, Blackcap stops without guessing. Non-numeric FoodKeeper guidance such as When Ripe or Not Recommended therefore does not create an automatic date.
  6. Choose the starting date. A valid supplied purchase date/time is used when available. If intake does not provide one, Blackcap uses the organization's local current date.
  7. Write the estimate once. The selected shelf-life days are added to the starting date and stored on the Package as Estimated Best By with day precision.

The estimate is intentionally one-time. Later FoodKeeper refreshes, profile edits, or Storage Location changes do not rewrite existing Package dates. Estimated Best By is display-only/system-generated and is never offered as a manual date-type choice. If a user edits an estimated date, Blackcap automatically changes its type to the normal Best By type.

No estimate is created when any required input is missing or ambiguous: there is no matching active FoodKeeper profile, the Storage Location cannot be mapped to Pantry/Refrigerator/Freezer, or the selected profile has no numeric duration for that zone. In those cases the Package simply remains No Date until a user enters one. Platform administration of the catalog, USDA refresh behavior, and fallback/customization rules are documented under Platform Configuration โ†’ FoodKeeper Shelf Life.

Kitchen Inventory keeps availability and expiration filters independent. In Full Inventory Tracking, Expiration offers All Dates, Expiring Soon, Expired, Expired or Expiring, and No Date. The logical Inventory tile only receives an aggregate warning when every relevant on-hand dated Package needs attention: any safely current dated Package keeps the tile visually normal; all relevant dated Packages expired produces the stronger expired treatment; otherwise all dated Packages being expired/expiring with at least one not-yet-expired Package produces the subtler Expiring Soon treatment. Undated Packages are neutral rather than being treated as expired.

Current implemented behavior

Shopping Lists

Shopping lists are organization-scoped saved records. Cards in the Admin UI use consumer-friendly smart names, recipe thumbnails, active/completed state, and icon-first actions.

Smart names use a friendly date and recipe summary, for example:

May 22, 2026 ยท Cheeseburger Pie +1 Recipe

If duplicate names are created for the same date/recipe combination, Blackcap appends a suffix such as -1 or -2.

Completed lists are hidden from Shop a List and Edit Shopping List selectors until they are reopened from Shopping Lists. A completed list cannot remain active; completing an active list clears the active-list state.

Meal Planner source behavior

Meal Planner can create shopping lists from selected planned days/slots or, when nothing is selected, from the current configured/working week.

Recipe-backed meal-plan entries contribute recipe ingredients through the existing shopping-list generation path, including the saved recipe multiplier. Manual meal items such as French fries, 2 salad kits, or Burger sauce are treated as ingredient-style shopping candidates. If a manual meal item is not canonical-linked, it remains reviewable the same way an unresolved recipe ingredient is reviewable.

Meal Planner does not directly manage Kitchen Inventory, On Hand state, grocery departments, barcode capture, or inventory intake. Those behaviors remain owned by Shopping Lists, Shop a List, Kitchen Inventory, and Database Admin canonical/department cleanup.

Edit Shopping List

Edit Shopping List is the Admin composition and repair page. It is not the checkoff surface.

It supports:

  • selecting an editable, non-completed shopping list;
  • changing recipe multipliers with fraction controls such as ยผ, ยฝ, ยพ, 1, and 1 ยฝ;
  • removing recipes from a list;
  • adding and removing truly manual shopping items only;
  • live ingredient preview grouped by Recipe, Department, or None;
  • a collapsible Ingredient Preview panel;
  • responsive recipe tiles when Ingredient Preview is collapsed;
  • automatic focus on the manual item entry field;
  • Enter/Tab to quickly create the next manual item entry;
  • unsaved-change warnings when switching lists or navigating away;
  • AJAX save/rebuild behavior without a full page refresh.

Data Admin, Org Admin, and System Admin users can also use Rebuild. Rebuild regenerates recipe-derived ingredients from the current list recipes, multipliers, and manual items. It is a safe repair action if generated ingredient rows ever drift from the list's durable inputs.

Shop a List

Shop a List is the execution experience for shopping.

Admin and Mobile Shop a List support:

  • checking items on/off;
  • grouping by Recipe, Department, or None;
  • filtering by Kitchen Inventory status: All items, On hand, or Need to shop;
  • adding manual shopping items in-place;
  • undo after removing a manual item;
  • completing the list.

Admin Shop a List also includes grocery department management and drag/drop assignment. Dragging an item into a department changes the item's current department and updates the canonical department mapping so future lists are grouped better.

Mobile Shop a List includes a long-press department reassignment flow. Long-press an ingredient to open a modal, view the current department, choose a new department, or add a new department and immediately assign the item to it.

Completing a list marks only checked items as on hand in Kitchen Inventory. Unchecked items are skipped.

Inventory behavior and scope

Kitchen Inventory keeps the existing organization-scoped logical item as the top-level identity while optionally tracking exact retail Products and individual physical Packages beneath it. Generic inventory remains fully supported: barcode, Product, package size, and precise quantity are never required.

Logical ingredient identity is intentionally separated from recipe preparation text and grammatical number. Blackcap removes unambiguous preparation/state/source wording and normalizes recognized plural nouns to singular before a recipe-backed or manually entered shopping item becomes a Kitchen Inventory identity, while preserving meaningful ingredient qualifiers. For example, large eggs at room temperature becomes canonical large egg, poached pears halved and cored becomes pear, red potatoes cut into 1-inch chunks becomes red potato, melted butter becomes butter, recipe homemade pie crust becomes pie crust, and apricot jam heated and strained becomes apricot jam. Cooking/source-state words such as poach, poached, recipe, homemade, heated, and strained are preparation/provenance rather than inventory identity. Blackcap uses LemmInflect dictionary-backed noun morphology rather than maintaining its own s/es suffix rules, and disables out-of-vocabulary guessing so naturally s-ending foods such as asparagus, molasses, and couscous remain intact. Original recipe and manual shopping display text remains unchanged for human-readable quantity/context. Editing an existing logical item keeps its inventory_item_id stable even when the display/canonical identity changes. This preserves Product, Package, Activity, and other child relationships and avoids attempting to insert the existing primary key under a new identity.

Implemented behavior includes:

  • ingredient visuals on Admin and Mobile Kitchen Inventory prefer the Blackcap master ingredient catalog's locally cached preferred image (normally the synchronized 96 ร— 96 TheMealDB image) when the inventory identity matches a canonical/display name, alias, or provider source name; the existing inventory emoji remains the fallback when no preferred cached catalog image is available, and rendering never requires a live TheMealDB request;
  • Admin and Mobile Kitchen Inventory pages with search/filter by storage location and On hand/Not on hand/All state;
  • manual logical-item add/edit, archive/restore, department, storage location, and notes;
  • zero, one, or many exact Products beneath one logical item;
  • zero, one, or many physical Packages, including different brands/products at the same time;
  • Admin inventory tiles use the compact Package badge as the package-count indicator; the tile body does not repeat text such as 2 physical packages;
  • durable Package current quantity with Exact/Calculated/Confirmed/Estimated/Unknown source/confidence semantics;
  • a shared package-fullness slider with Empty / Low / ยผ / ยฝ / ยพ / Full stops, plus optional precise supported-unit entry;
  • current quantity aggregation only across compatible measurement dimensions; incompatible/unknown quantities are shown rather than guessed;
  • โ•‘โ–ˆโ•‘โ–Œโ•‘โ•‘ Scan Product opens the rear camera immediately, uses browser BarcodeDetector when available with an in-memory decoder fallback, and retains manual barcode entry when camera access is unavailable;
  • every decoded Product lookup stays open for review before mutation, with editable Product name, brand, and package size/unit plus Accept / Retry / Cancel;
  • Product/package details remain visible from the logical Kitchen Inventory item and can be corrected later; corrections retain provider provenance (for example Open Food Facts) and reconcile full/fraction-tracked package capacity without overwriting independently confirmed exact remaining amounts;
  • UPC-A, UPC-E, EAN-8, and EAN-13 normalization into a canonical GTIN identity;
  • local Product cache first, then the configured open Product provider (Open Food Facts by default), with manual Product entry as the non-AI fallback;
  • temporary Product Photo Review capture that first attempts built-in barcode/Product reconciliation and lets the user manually confirm Product identity and package fullness;
  • optional asynchronous โœจ AI Product & Fullness Review with Quality Profile/AI Seed confirmation, recipe-photo-style progress reporting, and explicit review before Product/package changes are applied;
  • a separate top-level ๐Ÿ“ท Photo Inventory action on Admin and Mobile Kitchen Inventory can analyze one overview photo containing several visible ingredients; each AI finding independently proposes an existing logical-item match or a new logical item, an exact existing/new physical package, and a coarse fullness estimate for review;
  • overview-photo findings have Apply Reviewed Result / Ignore controls rather than Apply All. When AI cannot safely identify a specific existing package, the user must explicitly choose an active package or New package before fullness can be applied;
  • a UPC/GTIN is treated as an assigned Product identifier and is never invented from front-label text. When a reviewed finding identifies an existing package, Blackcap can reuse the barcode already stored on that package's Product; it can also suggest one unique strongly matching local Product barcode from reviewed Product name/brand/package-size metadata. Selecting an existing package during review can fill its known barcode and Product details while preserving any value already supplied by the photo/reviewer;
  • Product-photo and overview-photo captures are separate staging workflows: Product photos stay tied to one logical item/package while overview photos are deliberately unlinked so they can affect several items. Both are deleted after review/discard and abandoned captures are automatically purged; when AI is used, the provider input image is retained only in that AI Usage event's What Happened evidence and follows the AI Usage retention lifecycle;
  • conservative deterministic runout ranges when current quantity and enough Letโ€™s Cook consumption history are available. Forecasting uses one continuous observed-history window across retained detail and monthly summaries (avoiding retention/month overlap), counts quiet time with no consumption, requires at least two uses spanning at least three days, widens sparse-history ranges, caps confidence when current package quantity is only estimated or the most recent usage evidence is stale, and learns demand from the quantity reported by Letโ€™s Cook rather than understating usage when only part of that quantity could be reconciled to known Packages.
  • ingredient-aware weight โ†” volume reconciliation. Same-family conversions remain direct (3 Tbsp = 1.5 fl oz, 1 lb = 16 oz). When a recipe volume must reduce a weight-tracked package, or vice versa, Blackcap resolves the logical Kitchen Inventory ingredient against the platform Ingredient Densities catalog and bridges through g/mL. For example, seeded all-purpose flour uses 0.507 g/mL, so one US cup is about 120 g; a 5 lb flour bag can therefore be depleted by cup-based recipe usage.
  • if no ingredient-specific density row matches, Blackcap uses the platform Water/default fallback (1.000 g/mL by default), records that a fallback assumption was used, and treats the resulting package/runout estimate as low confidence. This deliberately favors useful behavior for unknown liquids while keeping the assumption visible. Counts and lengths are never guessed across dimensions.

Recent purchase, Letโ€™s Cook consumption, correction, and discard activity explains quantity changes without becoming the source of truth. Package quantity remains durable after old activity is summarized and purged.

Department resolution order

When rendering or grouping a shopping item, Blackcap resolves grocery department in this order:

  1. Item-level department override.
  2. Current organization's canonical item department mapping.
  3. Platform/default canonical item department mapping.
  4. Other / Uncategorized.

Department changes made through Admin drag/drop or Mobile long-press should improve future lists by updating the canonical item mapping.

Database Admin data-management views

Database Admin includes the following relevant resources:

  • Grocery Departments โ€” department list and ordering.
  • Inventory Locations โ€” storage locations used by Kitchen Inventory.
  • Kitchen Inventory Items โ€” organization-owned active and archived inventory records, including lifecycle status and the remembered pre-archive on-hand state.
  • Inventory Products โ€” optional exact retail Product/GTIN identities associated with logical items.
  • Inventory Packages โ€” owned physical containers and their durable quantity/state/location.
  • Inventory Activity โ€” recent quantity-change evidence subject to summarize-before-purge retention.
  • Inventory Monthly Summaries โ€” compact long-term aggregates used for reporting/forecasting.
  • Inventory Disposition Rules โ€” remembered Track/Do Not Track decisions for Shopping intake.
  • Inventory Photos / Photo Links โ€” internal staging records for temporary Product-photo and Kitchen Inventory overview-photo captures. Product-photo captures use logical/Product/Package links; overview captures are intentionally not linked to one item because one image can produce several reviewed findings. These photos are not durable Kitchen Inventory media; retained AI input images live in AI Usage evidence instead.
  • Shopping Lists โ€” saved shopping-list headers.
  • Shopping List Items โ€” individual shopping rows and check state.
  • Shopping List Item Sources โ€” recipe/manual attribution for rows.
  • Item Department & Storage Map โ€” canonical item mapping to grocery department and default storage location.

The Item Department & Storage Map resource includes a Review Uncategorized workflow. It surfaces canonical items from recipes, shopping lists, and Kitchen Inventory that are missing a department or still map to Other / Uncategorized. A data admin can review one suggestion at a time and assign both grocery department and default Kitchen Inventory storage location.

For Kitchen Inventory Items, the Database detail drawer exposes a Lifecycle Status safe edit with Active / Restored and Archived / Recently Deleted choices. This is not a raw status-column update: Blackcap calls the Kitchen Inventory domain service, preserves active-organization scope, writes the normal audit events, forces archived items off hand, and restores the remembered on-hand state when an item is reactivated. The lifecycle field requires both Database Admin edit access and inventory.delete.

Product scanning and privacy

Barcode scanning is additive and transient. The camera frame is used only to decode a barcode and is not stored as scan history. Blackcap persists useful final Product data such as normalized GTIN, name, brand, package size, provider/source metadata, and the logical-item association. A provider failure or unknown code never blocks normal Shopping or Inventory; manual Product entry remains available.

Product-photo capture is also transient. Blackcap stages an optimized image only long enough to run built-in barcode reconciliation, allow manual Product/fullness review, andโ€”only when the user explicitly opts inโ€”submit it to the selected AI provider. Applying or discarding the review removes the staged Product photo, and abandoned staging is purged automatically. If AI is used, the exact staged image supplied to the provider is copied into the AI Usage What Happened evidence so the input can be reviewed alongside the structured output; that evidence is retained and purged with AI Usage, not as Product media.

๐Ÿ“ท Photo Inventory is a separate Kitchen Inventory-level workflow. Its transient overview photo is not attached to one logical item. AI can identify several visible ingredients in one image, compare each against the organization's current logical items/packages, and suggest a new logical item when no reasonable existing match exists. Every finding remains suggestion-only until the user reviews its logical item, chooses an existing physical package or New package, confirms fullness, and applies that finding. The server rejects an overview apply with no explicit package choice or fullness and never falls back to the first package for an item. New logical-item names are routed through the normal Kitchen Inventory normalization/canonicalization path before saving.

The Product/package details popup shows only active physical packages; Empty/Discarded package history is retained in data/history surfaces but is not presented as current stock. Mobile Product details use one top-right โœ• Close action rather than a separate cancel/back control plus a bottom Done action.

Both Inventory Photo AI surfaces use the same Quality Profile/funding conventions as other AI review surfaces: Organization and Personal funding choices show the currently available AI Seed balance (or Unlimited), unaffordable sources are disabled, and the checkbox confirms the displayed AI Seed use. AI work is shown as one persistent step checklistโ€”start, prepare image, analyze identity/fullness, validate resultโ€”with completed steps checked off and the current step highlighted. The separate status box is reserved for failures, retry/recovery guidance, and review/completion messages rather than repeating the active checklist step. Gemini structured-image requests retain Blackcap's strict local validation and can fall back from provider-side JSON-schema/media hints when Gemini returns a pre-generation 400 INVALID_ARGUMENT compatibility rejection.

Quantity history and forecasting

Detailed Inventory Activity is retained for 30 days by default using the organization-scoped inventory.activity_retention_days setting. Before detail is purged, Blackcap folds compatible quantities into monthly logical-item summaries. The summarize-and-purge operation is idempotent and uses the existing Data Cleanup/scheduled purge orchestration.

Forecasting is deterministic and conservative. It uses durable current quantity plus recent Letโ€™s Cook consumption and older monthly summaries. Purchases do not count as consumption. If quantity or history is insufficient, Blackcap says the estimate is unavailable rather than inventing a date. When enough evidence exists, the UI shows a range and confidence instead of false precision.

Ingredient density conversions

Blackcap keeps measurement semantics strict: cup, Tbsp, tsp, fl oz, and ml are volume; oz, lb, g, and kg are weight. It does not reinterpret weight ounces as fluid ounces. The platform-owned ingredient_density_profiles catalog is consulted only when a Kitchen Inventory calculation must cross those dimensions. Ingredient-specific matches use the logical inventory name/aliases, and the longest specific match wins (for example, whole-wheat flour can beat the more general flour match). System Admins can view, add, edit, activate, or deactivate non-fallback rows at Platform Configuration โ†’ Ingredient Densities.

Density conversion is part of Letโ€™s Cook completion preview, final package depletion, Inventory Activity normalization, and Expected Runout history normalization, so the amount shown before Finish, the committed current quantity, and forecast demand use the same arithmetic. Known catalog density bridges cap otherwise-high confidence at medium because culinary density is approximate; the Water/default fallback caps confidence at low. Editing the platform catalog affects future calculations and forecast interpretation but does not rewrite already-stored physical package quantities.

Long-term north star

The long-term value is inventory-aware shopping:

  1. Blackcap knows what is already in Kitchen Inventory.
  2. Shopping-list generation flags or filters items already on hand.
  3. Needed items can later be associated to purchasable products.
  4. A future grocery-provider handoff can send needed products to a cart.
  5. After purchase/delivery, Blackcap can update Kitchen Inventory from confirmed checked/purchased items.

Implementation guardrails

  • Keep route handlers thin.
  • Use blueprints and service/repository layers.
  • Do not add direct SQL to route handlers.
  • Keep household data organization-scoped.
  • Product barcode cache may be platform-level.
  • Barcode lookup must have a manual fallback.
  • Mobile interactions must remain fast and touch-friendly.
  • Avoid confirmation prompts for low-risk manual item removals; prefer undo toasts.
  • For advanced Admin UI pages, preserve the successful scroll pattern: header panels can scroll fully away, primary panels fill the visible viewport, internal scrollbars remain fully visible, and panel/page scroll handoff stays smooth.

Optional automatic tracking

Organization administrators can control Track Kitchen Inventory from Organization Details and Organization configuration. The setting defaults On for existing and new organizations so upgrades preserve Blackcap's prior behavior.

When the setting is Off, Kitchen Inventory becomes manual-only rather than disappearing. Users with the normal permissions can still open Kitchen Inventory, add/edit/archive/restore items, move storage locations, and explicitly change on-hand state. Turning tracking off does not delete, archive, clear, or otherwise rewrite existing inventory.

Indirect workflows continue their own work but suppress their Kitchen Inventory side effect. In the current implementation this includes Have It / Already Have It, normal shopping-list completion, Shop With/assisted-shopping completion, and Letโ€™s Cook completion. The shopping item/list or cooking-session action itself still completes and the UI reports or records that inventory tracking is off. When tracking is On, Letโ€™s Cook consumes only ingredients persisted as used, applies the session's scaled structured quantity, and depletes the oldest compatible physical Packages first. Admin completion previews those estimates and accepts final remaining-quantity corrections; Mobile uses the same assumptions automatically to keep the completion flow compact.

Suppressed changes are not queued for replay. Turning tracking back On affects future automatic workflows only, and one organization's setting never changes another organization's behavior.

Logical uniqueness and Have It

Kitchen Inventory enforces one logical item per organization and normalized ingredient identity. Storage location is a mutable attribute, so Have It updates and moves the existing item rather than creating a second Pantry/Refrigerator/Freezer record. Migration 206 reconciles existing duplicate rows before adding the unique index.

Recently Deleted, restore, and retention

Authorized users can delete a Kitchen Inventory item from its Admin or Mobile tile with the compact ๐Ÿ—‘๏ธ action. The user-facing action archives the item rather than immediately hard-deleting it.

Archived items:

  • disappear from active On hand, Not on hand, and All active views;
  • stop counting as currently on hand;
  • do not satisfy shopping-list Have It checks;
  • retain organization, canonical identity, location, department, notes, and safe audit context;
  • appear in the authorized-only Recently deleted view;
  • can be restored during the configured retention window.

If the item has Product/Package tracking, explicitly choosing Not On Hand or deleting/archiving the logical item marks every non-terminal physical Package beneath every Product as Empty first. Product identity/history rows are retained; Products themselves do not carry an on-hand state. A later restore does not resurrect quantity from those emptied Packages. Generic logical items without Product/Package tracking continue to use their normal on-hand lifecycle.

The default retention window is 14 days. The Recently Deleted view shows the archived time, actor, storage location, expected purge time, and Restore action. Archived rows also appear immediately in Admin โ†’ Data Cleanup โ†’ Manual purge selected records, where an authorized administrator can preview and permanently purge a selected item early after the normal typed confirmation.

A later add/Have It operation for the same organization-scoped canonical identity restores and updates the archived row instead of creating a duplicate. This works with the migration 206 uniqueness rule.

Deletion/restoration requires inventory.delete. System Admin (in the selected organization context), Org Admin, and Data Admin have this permission by default. Operator and Contributor do not. Server-side permission and organization predicates are authoritative.

Migration 212_inventory_archive_retention.py adds the archive metadata and lookup/purge indexes. Permanent removal occurs only through the existing scheduled purge framework after the retention threshold.

On this page