add core features (#14)
Build & Deploy Formulation / Build & Push Image (push) Failing after 15s
Build & Deploy Formulation / deploy (push) Skipped

Reviewed-on: #14
Co-authored-by: Nicholas Ward <nicholaspward@outlook.com>
This commit was merged in pull request #14.
This commit is contained in:
2026-08-18 18:22:34 -05:00
committed by nicholas
parent 20e23b100f
commit 2a1e16ed30
125 changed files with 23392 additions and 2082 deletions
+28
View File
@@ -0,0 +1,28 @@
# Formulation Documentation & Knowledge Base
Welcome to the Formulation Help Center. This documentation explains the architecture, business logic, and operational workflows for managing recipes, ingredients, costs, units of measure, inventory, and archives.
---
## Knowledge Base Directory
### 🚀 Getting Started
- [Workspace Navigation & Global Search](./getting-started/workspace-navigation.md): Navigating workspaces, filtering catalogs, global search, and keyboard shortcuts.
### 🍳 Recipes & Formulas
- [Scaling, Batching & Yield Calculations](./recipes/scaling-and-yields.md): Interactive scaling, yield conversions, weight-based auto-yields, and portion control.
- [Baker's & Standard Percentages](./recipes/bakers-percentages.md): Flour basis calculation, dynamic target weights, and formula ratios.
- [Sub-recipes & Prep Methods](./recipes/sub-recipes-and-prep.md): Nesting recipes as ingredients, prep instructions, headers, notes, and equipment tracking.
### 🌿 Ingredients & Units of Measure
- [Units of Measure & Custom Equivalencies](./ingredients/units-and-equivalencies.md): Dimensional systems (mass, volume, count), canonical conversions, density measures, and USDA nutrition mapping.
### 💰 Costing & Purchasing
- [Purchase Items, Pack Sizes & Recipe Costing](./costing/purchase-items-and-costing.md): Invoices, pack configurations, yield factors, price history, food cost per batch, and cost per serving.
### 📦 Inventory Management
- [Inventory Steps for Success (5-Week Implementation Roadmap)](./inventory/inventory-calendar-steps-for-success.md): Full operational guide for going from initial setup to first live period-end inventory count.
- [Count Sheets & Storage Locations](./inventory/count-sheets-and-locations.md): Location-specific sheet-to-shelf counting, on-hand inputs, and live extended valuations.
### 🗄️ Archive & Trash Lifecycle
- [Archive & Lifecycle Management](./archive/lifecycle-and-restoration.md): Soft-deletion, catalog filtering, multi-item batch restore, and safe permanent deletion guards.
@@ -0,0 +1,23 @@
# Archive & Lifecycle Management
Formulation implements a two-stage deletion lifecycle (Soft Delete $\rightarrow$ Hard Delete) with automated dependency safeguards to protect culinary data integrity.
---
## 1. Soft Deletion (Archiving)
- When an ingredient, recipe, or recipe book is deleted, it is **soft-deleted** (`deleted_at` timestamp recorded) rather than purged immediately.
- Archived items are immediately hidden from active searches, auto-complete dropdowns, and directory views.
- Active recipes that historically reference an archived ingredient remain intact without breaking calculations.
---
## 2. Archive Workspace (`/app/archive/`)
The Archive workspace allows viewing and managing all removed items:
- **Filter by Entity**: Filter by *All*, *Recipes*, *Ingredients*, or *Recipe Books*.
- **Multi-Item Batch Selection**: Select multiple items using checkboxes to perform bulk actions.
- **Batch Restore**: Instantly restore selected items back to the active catalog.
- **Safe Permanent Deletion**:
- Permanently purges items from the database.
- **Dependency Safeguard**: Formulation automatically verifies whether an item is still referenced by any active recipe or sub-recipe. If dependencies exist, hard deletion is blocked with a clear warning explaining where the item is currently used.
@@ -0,0 +1,25 @@
# Purchase Items, Pack Sizes & Recipe Costing
Accurate recipe food costing relies on mapping real-world vendor purchase packages to canonical ingredients.
---
## 1. Purchase Items & Pack Configurations
A **Purchase Item** represents a commercial package purchased from a vendor or distributor:
- **Pack Size & Unit**: e.g., `50 lb Bag`, `6 x 1 Gallon Case`, `16 oz Container`.
- **Cost**: Total package purchase price (e.g. `$24.50`).
- **Yield Factor (%)**: The usable portion percentage after trimming or prep (e.g. 85% usable yield on trimmed beef tenderloin, 100% on flour).
- **Unit Cost**: Automatically computed per base unit (e.g. `$0.00108 / gram` or `$0.49 / lb`).
---
## 2. Recipe Food Costing Breakdown
When viewing a recipe's **Cost** tab:
1. **Line Cost**: Each ingredient's line item cost is calculated as:
$$\text{Line Cost} = \frac{\text{Quantity} \times \text{Unit Cost}}{\text{Yield Factor}}$$
2. **Total Batch Cost**: The sum of all line item costs for the batch.
3. **Cost per Serving**: Total Batch Cost divided by total yield servings.
4. **Food Cost % (Target Selling Price)**:
$$\text{Suggested Price} = \frac{\text{Cost per Serving}}{\text{Target Food Cost \%}}$$
@@ -0,0 +1,36 @@
# Workspace Navigation & Global Search
Formulation provides a streamlined, fast, centralized directory for managing all culinary data across your operation.
---
## 1. Directory Workspace & Workspace Pills
The home directory (`/app/`) categorizes items into distinct workspaces using top pill badges:
- **Recipes** (Blue badge): Standalone formulas, prep recipes, and batch formulations.
- **Ingredients** (Green badge): Raw culinary ingredients, allergens, density conversions, and supplier links.
- **Recipe Books** (Purple badge): Curated collections and menus of recipes (e.g. *Dinner Menu*, *Cocktails*, *Bakery Line*).
- **Purchase Items** (Cyan badge): Commercial vendor packages, invoice pack sizes, prices, and vendor SKUs.
- **Inventory** (Teal badge): Active and past inventory count sessions with on-hand valuations.
- **Archive** (Neutral link): Soft-deleted items ready for restoration or permanent purge.
---
## 2. Global Search & Autocompletion
- **Omnibox Search**: Search across recipe titles, ingredient names, aliases, and purchase items simultaneously.
- **Type Filtering**: Narrow search results by specific entity type directly from the search dropdown filter.
- **Keyboard Navigation**:
- <kbd>Tab</kbd> / <kbd>Arrow Down</kbd>: Highlight matching search candidates.
- <kbd>Enter</kbd>: Open the selected recipe or ingredient detail card immediately.
- <kbd>Escape</kbd>: Clear search and close active popups.
---
## 3. Detail Utility Bar
Every single item detail page features a fixed top utility bar containing:
- **Workspace Breadcrumbs**: Direct navigation back to the active directory workspace.
- **Global Search**: Search and jump to other items without returning to the home screen.
- **New Action Button (`+ New`)**: Quick creation modal for recipes, ingredients, recipe books, or count sessions from anywhere in the app.
@@ -0,0 +1,30 @@
# Units of Measure & Custom Equivalencies
Formulation maintains a rigorous, multi-dimensional unit conversion engine that enforces physical dimensional rules while supporting culinary volume-to-weight equivalencies.
---
## 1. Dimensional Systems
Every unit belongs to a fundamental physical dimension:
- **Mass** (Base unit: `gram`): `gram`, `kilogram`, `pound`, `ounce_mass`.
- **Volume** (Base unit: `milliliter`): `milliliter`, `liter`, `cup_us` (240 mL legal), `tablespoon_us`, `teaspoon_us`, `fluid_ounce_us`.
- **Count** (Base unit: `each`): `each`, `clove`, `head`, `bunch`.
- **Temperature** (Affine scale): `fahrenheit`, `celsius`.
---
## 2. Density & Ingredient-Specific UoM Equivalencies
Because ingredients possess different bulk densities (e.g. 1 cup of all-purpose flour = ~120g, whereas 1 cup of honey = ~340g), volume-to-mass conversions require density records.
### A. UoM Equivalencies Panel
- On each ingredient page, the **UoM Equivalency** tab allows defining custom portion measurements:
- *Example*: `1 cup = 125 g`
- *Example*: `1 medium apple = 182 g`
- *Example*: `1 clove garlic = 3 g`
### B. Resolution Precedence
1. **Reviewed Portions / Measures**: Checked first for an exact unit match (e.g. `cup` or `each`).
2. **Bulk Density Measurements**: Checked if converting between standard volume and mass dimensions.
3. **Canonical Unit Factor**: Applied for within-dimension conversions (e.g. `lb` to `oz`).
@@ -0,0 +1,26 @@
# Count Sheets & Storage Locations
Inventory in Formulation is designed for fast, sheet-to-shelf counting across physical kitchen storage locations.
---
## 1. Storage Locations
Organize physical storage areas into logical zones:
- **Walk-in Cooler**: Dairy, produce, raw proteins, prepped batch items.
- **Dry Storage**: Flours, grains, spices, oils, canned goods.
- **Freezer**: Frozen stocks, puff pastry, frozen proteins.
- **Bar / Front of House**: Spirits, syrups, mixers, garnishes.
- **Line Stations**: Sauté station drawers, prep table bins.
---
## 2. Conducting an Inventory Count
To conduct a count session:
1. Go to **Inventory** in the directory toolbar.
2. Select **+ New Count Session**.
3. In the count session view, select a location filter to display items in shelf order.
4. For each line item, enter the on-hand quantity in the **Count** box.
5. Review the **Extended Value ($)** column, which automatically computes the value based on current vendor purchase costs.
6. Select **Finalize Count** to complete the count and lock the valuation for accounting.
@@ -0,0 +1,100 @@
# Inventory Steps for Success
A structured 5-week roadmap to build out recipes, configure purchasing units and costs, organize location-specific count sheets, test inventory counting, and successfully conduct your first live inventory.
---
## 5-Week Roadmap Overview
```mermaid
gantt
title Inventory Onboarding & Setup Roadmap
dateFormat X
axisFormat Day %d
section Week 1
Recipes & Ingredients Setup :active, 1, 7
section Week 2
Purchasing Units & Costs :2, 14
section Week 3
Location Count Sheets :3, 21
section Week 4
Dry-Run Test Counts :4, 28
section Week 5
First Live Inventory & Analytics :5, 35
```
---
## Week 1: Build Out Recipes & Ingredients Tables
> **Week 1 Goal**: Your complete recipe database and canonical ingredient list are populated and ready for kitchen use.
| Day | Action Item | Details & Instructions |
|---|---|---|
| **Monday** | **Goal Kickoff** | Define the scope of prep items, sub-recipes, and raw ingredients to be tracked. |
| **Tuesday** | **Start with Prep Recipes** | Begin by entering your prep recipes and sub-recipes. As you add prep recipes, your canonical ingredient list will automatically populate. |
| **Wednesday** | **Audit & Merge Ingredients** | Review your ingredient catalog. Identify duplicates or near-duplicates (e.g. "kosher salt" vs "salt kosher") and merge them into single canonical ingredients. |
| **Thursday** | **Duplicate Multi-Type Items** | Make distinct copies of ingredients where you use multiple varieties or grades of the same item (e.g. *Flour - All Purpose* vs *Flour - Bread High Gluten*). |
| **Friday** | **Review Kitchen Database** | Verify that recipes have components, steps, and yields properly structured. |
| **Saturday & Sunday** | **Milestone Check** | **Look at that!** You now have a complete, standardized recipe database that can be used actively on the kitchen line. |
---
## Week 2: Configure Costs & Purchase Units
> **Week 2 Goal**: All inventoried ingredients have verified purchase packages, unit costs, and yield factors.
| Day | Action Item | Details & Instructions |
|---|---|---|
| **Monday** | **Goal Kickoff** | Gather recent supplier invoices, receipts (e.g., Walmart, Sam's Club, US Foods, Sysco), and vendor order guides. |
| **Tuesday** | **Invoice Processing & Linking** | Ingest invoice lines into the system to extract package sizes, prices, and vendor SKU codes. |
| **Wednesday** | **Manual Costing** | For specialty or local market items without digital invoices, enter package costs manually on the ingredient cost panel. |
| **Thursday** | **Spreadsheet Import** | If you maintain vendor price lists in spreadsheets, upload or batch-map purchase packages into your catalog. |
| **Friday** | **Map New Purchase Items** | Use the Purchase Items table to map raw invoice line descriptions to their canonical formulation ingredients. |
| **Saturday** | **Audit Missing Costs** | Filter your ingredient directory to inspect which items are still unpriced. Add missing package sizes. |
| **Sunday** | **Milestone Check** | **Prep recipes now show real costs!** Take a well-deserved break—your recipe costing foundation is complete. |
---
## Week 3: Build Location Count Sheets
> **Week 3 Goal**: Sheet-to-shelf inventory count lists are configured for each physical storage area.
| Day | Action Item | Details & Instructions |
|---|---|---|
| **Monday** | **Goal Kickoff** | Identify all physical storage areas across your operation (e.g., *Walk-In Cooler*, *Dry Storage*, *Freezer*, *Bar*, *Line Drawers*). |
| **Tuesday** | **Create Count Sheets** | Go to **+ New** and select **Count Sheet**. Ensure count sheets are strictly location-specific. *(Note: Only managers can create count templates).* |
| **Wednesday** | **Order "Sheet to Shelf"** | Arrange ingredients in the exact physical order they appear on your shelves (top-to-bottom, left-to-right). This maximizes counting speed and prevents missed items. |
| **Thursday** | **Add Ingredients & Batches** | Add raw ingredients (green icon) and prepped batch recipes (blue icon) to each count sheet. Drag and drop to reorder. |
| **Friday** | **Set Count Units** | Verify and adjust count units (e.g. *Cases*, *Bags*, *Each*, *Pounds*) to match how cooks physically count each shelf. Count units default to the ingredient's primary purchase unit. |
| **Saturday & Sunday** | **Milestone Check** | **Almost there!** All location count sheets are structured and ready for validation. |
---
## Week 4: Test Run & Validate Inventory Lists
> **Week 4 Goal**: Perform a dry-run test count to uncover unit mismatch errors, pack size discrepancies, or missing items.
| Day | Action Item | Details & Instructions |
|---|---|---|
| **Monday** | **Goal Kickoff** | Schedule a 20-minute test run with key kitchen leads before service. |
| **Tuesday** | **Enter Test Count Values** | Enter a dummy quantity of **`1`** in every column (or enter last month's closing count). Save and submit each location sheet individually (do not submit total final count). |
| **Wednesday** | **Export Valuation Report** | Review the calculated on-hand values and line-item totals in the analytics review. |
| **Thursday** | **Identify Discrepancies** | Look for extended dollar values that look unusually high or low. This highlights where pack sizes (e.g. $50/case counted as 1 ea = $50 vs $2.08) or count units need calibration. |
| **Friday** | **Correct Count Templates** | Update pack sizes, count units, or ingredient equivalencies based on test run findings. |
| **Saturday & Sunday** | **Milestone Check** | **Take a deep breath!** Your inventory templates are calibrated, validated, and ready for real operational use. |
---
## Week 5: Conduct Your First Live Inventory
> **Week 5 Goal**: Successfully execute full period-end inventory, capture total valuation, and establish your inventory baseline.
| Day | Action Item | Details & Instructions |
|---|---|---|
| **Monday** | **Conduct Live Count** | Assign team members to their respective locations with mobile devices or clipboards. |
| **Tuesday** | **Add Items On the Fly** | If an unlisted item is discovered on a shelf during the count, add it on the fly. *(Remember to add it to the master count template afterward).* |
| **Wednesday** | **Review & Submit Count** | Once all location lists are filled, managers review pending location totals and submit the total inventory count. |
| **Thursday** | **Analyze Inventory Valuation** | Review the total dollar valuation report by storage location and ingredient category. *(Calculations finalize within minutes).* |
| **Friday** | **Export Accounting Reports** | Export your finalized inventory valuation breakdown categorized by GL accounting codes for bookkeeping. |
| **Saturday & Sunday** | **Celebrate Success!** | You now have a repeatable, accurate, high-speed inventory process embedded into your culinary operations! |
+28
View File
@@ -0,0 +1,28 @@
# Baker's & Standard Percentages
In baking and commercial food manufacturing, formulas use **percentages** to ensure recipe scalability and hydration control.
---
## 1. Standard Percentage vs. Baker's Percentage
### Standard % (Total Formulation Basis)
$$\text{Standard \%} = \frac{\text{Ingredient Weight}}{\text{Total Batch Weight}} \times 100$$
- In Standard Percentage mode, the sum of all ingredient percentages in the recipe equals **100%**.
- Use Standard % for confectionery, dressings, beverages, and general culinary batching.
### Baker's % (Flour / Basis Member Basis)
$$\text{Baker's \%} = \frac{\text{Ingredient Weight}}{\text{Total Basis Flour Weight}} \times 100$$
- In Baker's Percentage mode, the flour or designated base ingredients are flagged as **Base Members** (`basis_member = true`) and sum to **100%**.
- All other ingredients (such as hydration water, salt, yeast, sugar, and butter) are expressed as a percentage relative to the total flour weight (such as 75% hydration water, 2% salt, 1.5% yeast).
---
## 2. Using Interactive Percentage Editing
To configure and edit percentages in a recipe:
1. Open the recipe in edit mode.
2. Turn on the **Calculate %** toggle.
3. Select **Standard %** or **Baker's %**.
4. For Baker's %, select the **Base** check box for each flour or grain ingredient.
5. In the **%** column, enter the desired percentage for an ingredient. Formulation dynamically calculates the required physical weight and quantity in grams.
+41
View File
@@ -0,0 +1,41 @@
# Scaling, Batching & Yield Calculations
Formulation is a weight-first formulation engine designed to scale recipes across commercial batch sizes without calculation rounding drift.
---
## 1. Batch Multipliers vs. Yield-Target Scaling
Recipes can be scaled in two primary modes:
### A. Batch Multiplier (`x` Factor)
To scale by a batch multiplier:
1. Open the recipe in view mode or edit mode.
2. In the **Batch** field, enter a multiplier value (such as `0.5`, `2`, `5`, or `10`).
3. Every ingredient quantity scales proportionally by the exact factor.
### B. Target Yield Scaling
To scale to a specific finished yield target:
1. Open the recipe.
2. In the **Yield** field, enter the target finished quantity.
3. Select the desired yield unit from the unit list.
4. Formulation computes the required scale factor based on total recipe weight and updates all ingredient quantities immediately.
---
## 2. Weight-Based Auto-Yield Calculation
To enable automatic total yield calculation:
1. Open the recipe in edit mode.
2. Turn on the **Auto calculate total yield** toggle.
3. Formulation calculates the weight in grams for every ingredient using standard conversion factors or ingredient-specific density measurements.
4. The total recipe yield quantity updates automatically to equal the exact sum of all ingredient weights.
5. If an ingredient lacks a volume-to-weight equivalency, a notice appears: *"Auto yield excludes N ingredient amounts without a weight equivalency."*
---
## 3. Unit Conversion Safety
- Ingredients measured in mass (such as `g`, `kg`, `oz`, `lb`) convert directly across all mass units.
- Ingredients measured in volume (such as `cup`, `tbsp`, `tsp`, `liter`, `ml`) require an ingredient density measurement (such as `1 cup = 120 g`) to convert to mass.
- Cross-dimensional conversions without density data are rejected to maintain strict culinary accuracy.
+45
View File
@@ -0,0 +1,45 @@
# Sub-recipes & Prep Methods
Recipes in Formulation can nest other recipes as **sub-recipes**, enabling modular batch preparation and accurate cost and nutrition rollup.
---
## 1. Using Sub-recipes in Formulations
To add a sub-recipe to a recipe:
1. In the recipe editor, go to the **Formula** section.
2. In the ingredient search box, enter the name of the existing recipe.
3. From the search results, select the recipe (identified by the blue **Recipe** badge).
4. Enter the required quantity and select the unit of measure.
### Cascading Cost & Nutrition
- The sub-recipe's unit cost and nutritional profile are calculated based on its own ingredients and yield, and cascaded into the parent recipe.
- Changes to a base sub-recipe (such as *House Mayonnaise*) automatically propagate up to all dishes that include it (such as *Aioli*, *Tartar Sauce*, and *Sandwich Spread*).
---
## 2. Structured Prep Method
The **Prep Method** editor organizes kitchen instructions into ordered, sequential steps.
### Step-by-Step Instructions
1. In the recipe editor, go to the **Prep Method** section.
2. Select **Add Step** (or press <kbd>Enter</kbd>) to create a new step.
3. Enter the step instructions using imperative action verbs (such as *Combine*, *Preheat*, *Whisk*, or *Bake*).
4. To reorder steps, select and drag the 6-dot drag handle to the new position.
### Section Headings
To break complex multi-stage procedures into logical phases:
- End the step text with a colon `:` (for example, `To prepare the dough:` or `To bake:`).
- Formulation formats these entries as distinct section headers without numbered step bullets.
### Inline Prep Notes
To add non-actionable tips or precautions:
- Wrap the text in parentheses `(...)` (for example, `(Note: Chill the dough for at least 30 minutes before rolling.)`).
- Formulation formats these entries as italicized notes without numbered step bullets.
### Bulk Prep Import
To import an existing recipe procedure from text:
1. In the **Prep Method** header, select **Bulk Add**.
2. Paste the multi-line procedure into the text area.
3. Select **Import Steps**. Formulation automatically parses section headings, numbered steps, and notes into structured cards.