Recipes and the Recipe Library
Audience: User, Org Admin, Support, Developer Related: Importing And Discovery · Editing And Cache · Sharing · Social Import · Ai Image Generation · Adapt Recipe
The Recipe Library stores organization-scoped recipes captured from normal web pages, social sources, photos or screenshots, manual entry, shared recipes, and supported import formats. Users can search, filter, view, edit, share, rate, archive, restore, refresh, and assign recipes to meal plans or displays.
Recipe records are database-backed. Generated PDF, PNG, editable-content, thumbnail, and Made It artifacts remain managed cache or media files with database metadata.
Recipe time normalization is also write-time metadata. When a new/captured recipe has no explicit Total Time but has sufficient non-overlapping structured time buckets, Blackcap derives the Total Time once at the shared recipe-write boundary and stores the result in the recipe's canonical total_minutes field. Display/search/edit surfaces read that stored value rather than recalculating Total Time on every view. An explicit Total Time remains authoritative. Sparse metadata edits, such as renaming an AI/OCR-created recipe, preserve stored structured times and captured thumbnail/image metadata; if a legacy row is missing Total Time but still has sufficient component durations, the next normal recipe write repairs and persists total_minutes.
Core user tasks
- Add a recipe from a URL, social source, image, manual entry, share, or supported import.
- Search and filter the Recipe Library.
- Edit recipe metadata, ingredients, instructions, units, notes, layout, and orientation.
- Build or refresh PDF and display cache artifacts.
- Share, plan, shop, assign, cook, rate, archive, restore, or delete a recipe according to dependencies and permissions.
More information
- Importing and Discovery — Add recipes from normal URLs, images, manual entry, discovery, and supported import formats.
- Social Recipe Import — Capture and review recipe evidence from supported social-media sources.
- Editing and Cache — Edit recipe content and manage PDFs, display images, thumbnails, and other cache artifacts.
- Recipe Sharing — Create and manage recipe share links, invitations, acceptance, expiration, and dependencies.
- AI Recipe Image Generation — Generate, review, accept, retain, and clean up AI-created recipe images.
- Adapt Recipe — Create independently saved variations using organization dietary preferences and one-off guidance.
Canonical Recipe Types
Recipe Type now uses one server-side taxonomy across Admin, Mobile, API Tester, social/AI extraction, and the Chrome Extension. Selection lists are sorted by the current display label so future localized labels can determine their natural order, with Other deliberately pinned to the bottom. The normalization design deliberately keeps Blackcap's established meal-period categories instead of adding overlapping synonyms such as Main, Main Course, Main Dish, and Entrée.
| Current type | Keep/Rename | Canonical type | Reason |
|---|---|---|---|
| Breakfast | Keep | Breakfast | Established and useful. |
| Lunch | Keep | Lunch | Established; avoids forcing lunch recipes into an Entrée synonym. |
| Dinner | Keep | Dinner | Established Blackcap default. |
| Side | Rename | Side Dish | Clearer requested terminology. |
| Snack | Keep | Snack | Distinct lightweight category. |
| Dessert | Keep | Dessert | Distinct established category. |
| Drink (legacy/API example) | Rename | Beverage | Broad category covers cocktails/mocktails without extra overlap. |
| — | Add | Appetizer | Requested and distinct. |
| — | Add | Salad | Broad, useful library category. |
| — | Add | Soup / Stew | Broad, useful library category. |
| — | Add | Sauce / Condiment | Covers sauces, dressings, marinades, dips/spreads without multiplying overlapping types. |
| — | Add | Bread / Baked Good | Useful broad baking category distinct from Dessert. |
| Component | Keep | Component | Ordinary recipe that can be prepared as a direct make-from-scratch ingredient for a parent recipe. |
| — | Add | Other | Explicit fallback for recipes outside the concise taxonomy. |
The canonical taxonomy defines the allowed values, not a permanent visible sort sequence. User-facing selectors sort by the current display label so localized labels can determine the natural order, while Other always remains last. AI/social structured extraction is constrained to the canonical values and the server validates new recipe writes. The compatibility migration maps historical Side to Side Dish and Drink to Beverage; it does not collapse unrelated existing categories silently.
Component Recipes and structured yield
A Component is an ordinary organization-scoped recipe whose canonical Recipe Type is Component. It can still be viewed, edited, shared, printed, searched, and cooked directly. Blackcap also recognizes it as a make-from-scratch option when a non-Component parent recipe contains a structured ingredient name that exactly matches the Component recipe name. Matching is deterministic: no aliases, fuzzy matching, substring matching, synonyms, or AI are used, and candidates from another organization are never considered.
Component processing is intentionally one level deep. Blackcap inspects a normal parent recipe for direct Components, but it never inspects a Component recipe for more Components. A Component ingredient that happens to match another Component recipe remains an ordinary ingredient.
Component recipes use structured production yield rather than people served for quantity planning. For example:
Frangipane
Recipe Type: Component
Yield: 2 cups
The recipe record stores Component Yield in first-class nullable yield_quantity and yield_unit fields; existing yield metadata is migrated into those fields and Component support uses the normal measurement-unit registry. A Component yield is optional so older Component recipes remain usable, but automatic batch calculation requires a positive quantity plus a supported measurable unit. Blackcap does not substitute servings_count, Serves 8, or other people-serving metadata for Component yield.
During recipe creation/capture, Recipe Type remains a primary field. Choosing Component replaces the ordinary servings-focused input with the compact structured Yield quantity + unit input. Switching to any other Recipe Type keeps the established servings workflow. This applies to Admin/manual creation, Mobile/photo capture, Chrome Extension capture, social import preferences, and Recipe Discovery review. Extracted servings cannot overwrite an explicitly selected Component type/yield.
When a parent needs only part of a Component batch, Blackcap calculates the minimum practical batch from the parent ingredient quantity and Component yield, then applies the existing recipe multiplier constraints. Example: a parent needs 3/4 cup and the Component yields 2 cups, so the mathematical multiplier is 0.375x. If the Component has no limiting ingredients, 0.375x can be used. If it contains one egg, existing whole-egg rules may raise the batch to 1x; two eggs can permit 0.5x. The planner never rounds below the amount required.
Missing or incompatible yield units do not invalidate the Component relationship. Blackcap shows the required parent quantity and asks for a manual multiplier instead of guessing a conversion. User overrides are allowed, with a warning when the selected multiplier would produce less than the parent requires. Extra output caused by multiplier constraints is allowed and is not automatically added to Kitchen Inventory.
Recipe Quick View
Recipe names on interactive cards, rows, lists, selectors, and dialogs use a shared Recipe Quick View link when that surface does not already give the recipe name its own navigation/action. The dialog is read-only and organization-authorized. It shows the recipe image, name, description, Yield or Servings, Total Time, Clean Up, Rating, and Time & Effort pills, followed by ingredients, ordered steps, notes, and nutrition when present. Nutrition is collapsed by default.
Quick View uses the current organization/request presentation context rather than exposing raw stored recipe text. In particular, ingredients, applicable temperatures/measurements in instructions and notes, and Component Yield follow the active organization Preferred Recipe Units setting (As Written, US Customary, or Metric) using the same safe conversion helpers as normal recipe rendering/shopping workflows. Existing manually edited converted text is honored only when it belongs to the active unit preference. Recipe authorization remains organization-scoped through the normal Recipe Library lookup.
The shared link is intentionally not layered over the ordinary Meal Planner/Home recipe cards because those names already have feature-specific click behavior. Recipe names inside the Meal Slot Summary dialog do use Quick View, as do Recipe Library, Recipe Cart/Shopping List associations, Component prompts, Let’s Cook recipe search, selected-recipe configuration surfaces, and other recipe-name contexts that lack an existing hyperlink action. Print-only output, select-option text, editable recipe-name fields, and recipe names embedded in prose/status messages are not converted into links.
Cookbook Categories
Cookbook Categories are an organization-owned recipe taxonomy separate from Recipe Type, cuisine, tags, and meal type. Organizations start with no categories and can create any number of roots, nested to a maximum of 9 total levels. Categories keep stable public identities when renamed, reordered, or moved. A move reparents the category subtree; it does not rewrite recipe assignments.
A recipe can belong to zero, one, or many Cookbook Categories. Assignments are direct many-to-many relationships, so assigning a recipe to Winter › Soups does not create a second assignment to Winter. Descendant-aware search provides the hierarchy behavior instead. A recipe intentionally assigned to several categories can therefore appear in each of those direct locations in grouped views.
Cookbook Categories can also be selected during initial recipe creation. Admin/manual creation, URL capture, Mobile Add Recipe, Chrome Extension Quick Add/Capture Page/Social Recipe, photo/OCR/AI review, social import, shared-recipe import, and supported file import all use the same organization-scoped public category IDs and many-to-many relationship. Category selection is optional; organizations with no configured categories continue to create Uncategorized recipes normally. Mobile and the Chrome Extension use compact searchable multi-select controls rather than permanently rendering the full hierarchy. User selections persist through asynchronous extraction and Run AI Again and are not sent to, inferred by, or overwritten by AI providers.
Organization administrators manage the hierarchy directly inside Configuration → Organization → Cookbook Categories; there is no separate category-management page to leave Configuration for. A dedicated drag handle is used for drag/reorder so clicking a category name opens its associated-recipe viewer instead of accidentally moving the tree. An explicit Move action provides the keyboard/touch alternative and supports moving to another parent or back to Root. Moves reject cycles and any subtree placement that would create level 10.
The associated-recipes dialog shows direct assignments by default, with an optional Include subcategories view. Selected recipes can be Copy/Add assigned to another category while keeping the source assignment, or Move assigned so only the source category used for that operation is replaced; unrelated category assignments remain intact. Recipe Metadata supports multiple category selections, and Recipe Library bulk actions can add or remove category assignments without replacing every category on the selected recipes.
Recipe Library remains a flat alphabetical list by default. Its Category facet includes the selected category and all descendants and returns each matching recipe once in flat results. View by Category is optional and starts with groups collapsed; grouped results show direct assignments under each node, preserve ancestor context for filtered branches, and show a virtual Uncategorized group for recipes with no category. Each real category has a selection checkbox that selects every recipe assigned directly to that category or any descendant category into the existing Recipe Library bulk-selection set. The selection remains recipe-based: an individual recipe can be unchecked afterward, and the affected category/ancestor checkboxes become indeterminate until every recipe in their subtree is selected again. Existing Share, Change Type, Categories, Cart, Refresh, Archive/Delete, and other bulk actions therefore work identically whether recipes were selected individually or by category. Category selection uses the complete category subtree, not only the recipes surviving the current text/filter view. Home offers the same category filter/grouping semantics without adding category mass-selection. Meal Planner, Kiosk, and the full Let’s Cook recipe-search picker provide descendant-aware Category filtering while retaining their existing recipe tile/list presentation.