MenuMargin Pro

Business

Original Idea

Restaurant Costing Board A tablet-friendly web app that recalculates margins as ingredient prices change.

Product Requirements Document: MenuMargin Pro

1. Executive Summary

MenuMargin Pro is a tablet-optimized web application designed for high-touch industrial kitchen environments. It provides restaurateurs and chefs with real-time visibility into profit margins by dynamically recalculating recipe costs as ingredient prices fluctuate. By integrating directly with major food distributors and POS systems, the platform replaces manual spreadsheets with an automated, "local-first" tool that ensures profitability in a volatile market.

2. Problem Statement

In the 2026 economic landscape, ingredient prices are highly volatile. Chefs and restaurant owners traditionally rely on static spreadsheets to calculate dish costs, which quickly become outdated. This leads to "invisible margin erosion," where a restaurant may be selling a popular dish at a loss for weeks before noticing a price hike in a core ingredient like butter or protein. There is currently no kitchen-hardened solution that provides instant, recursive price updates across nested recipes.

3. Goals & Success Metrics

  • Goal: Reduce the time spent on manual recipe costing by 80%.
  • Goal: Prevent margin dips below 15% through real-time alerts.
  • Success Metric: Average margin retention across the menu remains within 2% of the target.
  • Success Metric: User engagement: 90% of chefs perform at least one price update or review per week.
  • Success Metric: System Latency: Recursive price updates for 1,000+ recipes must complete in under 500ms.

4. User Personas

  • Head Chef (Marco): Needs to update prices on the fly, often with wet or gloved hands. Focuses on recipe accuracy and yield loss.
  • Restaurant Owner (Sarah): Focuses on the "Menu Engineering Matrix." Needs high-level financial health reports and "Star/Dog" analysis.
  • Kitchen Manager (Dave): Responsible for ingredient syncing and supplier management. Needs to ensure the database matches physical invoices.

5. User Stories

  • As a Chef, I want to update the price of a single bulk ingredient (e.g., Flour) and have it instantly update the cost of all sub-recipes (e.g., Roux, Pasta) and final dishes.
  • As an Owner, I want to see a color-coded dashboard of my most profitable and least profitable items based on today’s actual market prices.
  • As a Kitchen Manager, I want to use my tablet in the walk-in freezer to log waste without losing data due to poor Wi-Fi.
  • As a Chef, I want the UI to have large touch targets so I can navigate the app while wearing prep gloves.

6. Functional Requirements

6.1 Ingredient & Unit Management

  • Precision Math Engine: Use Big.js for all calculations to prevent floating-point errors.
  • Unit Converter: Support for Mass (g, kg, lb, oz) and Volume (ml, l, cup, tbsp) with density mapping for ingredients (e.g., 1 cup of honey vs. 1 cup of flour).
  • Yield Adjustment: Field for "Waste %" per ingredient to calculate "True Cost."

6.2 Recipe Costing Engine

  • Nested Recipes: Support for "sub-recipes" (e.g., a "Mother Sauce" used in 10 different dishes).
  • Recursive Ripple: When a leaf ingredient price changes, all parent recipes must recalculate their cost basis automatically.

6.3 Dashboard & Menu Engineering

  • Quadrant Matrix: Visual scatter plot (using Nivo or Recharts) categorizing items into Stars, Plowhorses, Puzzles, and Dogs.
  • Margin Alerts: Push notifications or visual flags when a dish margin drops below a user-defined threshold (e.g., <65%).

6.4 Offline & Tablet Support

  • Local-First Storage: Use PowerSync + SQLite to allow full functionality in "Lie-Fi" kitchen environments.
  • Industrial UI: 60px+ touch targets, swipe-to-confirm actions, and high-contrast dark mode.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend: React v19.2.3 with Tailwind CSS v4.1.18 (Oxide Engine).
  • Component Library: Headless UI v2.2.9 (utilizing Anchor Positioning).
  • Backend: Node.js v24.13.0 (Krypton LTS) with Express.
  • Database: PostgreSQL with pg_ivm extension for incremental materialized view maintenance.
  • ORM: Prisma v7.2.0 (TypeScript-native engine).
  • Auth: Clerk with RBAC (User Metadata for "Kitchen" vs. "Owner" roles).
  • Offline Sync: PowerSync for bi-directional PostgreSQL-to-SQLite synchronization.

7.2 Integrations

  • Suppliers: Sysco (GraphQL API via APIC Portal), US Foods (EDI/A2A integration).
  • POS: Square/Toast for sales volume data (used in Menu Engineering Matrix).

8. Data Model

Ingredient

  • id: UUID
  • name: String
  • baseUnitPrice: Decimal (using Big.js)
  • unitOfMeasure: Enum (KG, L, etc.)
  • density: Decimal (g/ml, for mass-volume conversion)
  • yieldPercentage: Decimal (e.g., 0.85 for 15% waste)
  • updatedAt: Timestamp

Recipe

  • id: UUID
  • name: String
  • isSubRecipe: Boolean
  • targetMargin: Decimal
  • sellingPrice: Decimal
  • totalCost: Decimal (Materialized via pg_ivm or background worker)

RecipeIngredient (Junction)

  • recipeId: UUID (FK)
  • ingredientId: UUID (FK, can also link to another Recipe ID for nesting)
  • quantity: Decimal
  • unitOfMeasure: Enum

9. API Specification (Key Endpoints)

PATCH /api/ingredients/:id/price

  • Description: Updates the price of an ingredient and triggers the recursive ripple.
  • Request: { "newPrice": 45.50, "effectiveDate": "2026-02-01" }
  • Response: { "status": "queued", "affectedRecipesCount": 24 }

GET /api/reports/menu-engineering

  • Description: Returns data for the scatter plot matrix.
  • Response: Array<{ name: string, popularity: number, margin: number, quadrant: 'Star' | 'Dog' | ... }>

10. UI/UX Requirements

  • Bento Grid 2.0: Modular dashboard layout for scannable metrics.
  • Glove-Friendly Interaction: No dropdowns; use large-button "Segmented Pickers."
  • Visual Strobes: Red screen-edge glow for critical margin alerts.
  • Zero UI: Voice-to-text logging for "Wastage" entries via the Web Speech API.

11. Non-Functional Requirements

  • Performance: Recursive CTEs in PostgreSQL must resolve in <200ms for 5-level deep recipes.
  • Security: Clerk RBAC to ensure "Kitchen" users cannot view "Owner" profit reports or change "Selling Price."
  • Accessibility: WCAG 2.1 Level AA compliance, specifically focusing on high-contrast for low-light kitchen corners.

12. Out of Scope

  • Employee Payroll/Scheduling.
  • Customer-facing digital menus.
  • Automated purchasing (ordering ingredients automatically).

13. Risks & Mitigations

  • Risk: Data inaccuracy from supplier APIs.
    • Mitigation: Allow manual "Invoice Overrides" that flag discrepancies to the manager.
  • Risk: Tablet hardware failure in high-heat areas.
    • Mitigation: Web-app architecture allows any device to be used as a backup immediately.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize React 19.2.3 project with Tailwind 4.1.18.
  • [ ] Configure Node.js 24.13.0 (Krypton) backend.
  • [ ] Set up Prisma 7.2.0 with PostgreSQL.
  • [ ] Install Big.js and Currency.js for precision math.

Phase 2: Core Costing Engine

  • [ ] Create database schema for Ingredients, Recipes, and Junction tables.
  • [ ] Implement Math.js unit conversion utility.
  • [ ] Develop the Recursive CTE in PostgreSQL for ingredient price ripple.
  • [ ] Integrate Clerk for RBAC (Roles: owner, kitchen_staff).

Phase 3: Offline & Tablet UI

  • [ ] Implement PowerSync for local SQLite storage.
  • [ ] Build "Bento Grid" dashboard with Headless UI 2.2.9.
  • [ ] Implement "Large Target" UI patterns (60px buttons).
  • [ ] Build "Swipe-to-Confirm" component for destructive actions.

Phase 4: Data Visuals & Integrations

  • [ ] Integrate Nivo ScatterPlot for Menu Engineering Matrix.
  • [ ] Set up Sysco GraphQL consumer for automated price fetching.
  • [ ] Build "Margin Alert" notification system (Web Push).
  • [ ] Implement CSV/Google Sheets export for financial audits.