Feature: Pantry-Aware Meal Planner + Smart Shopping List (with Substitutions & Nutrition)

[hoangsonww]

Summary
Add a pantry-aware weekly meal planner that generates a smart shopping list, prioritizes ingredients you already have, suggests substitutions for missing items, and displays estimated nutrition per recipe/meal plan. Works across Web and Mobile, with optional offline support and cloud sync.

Motivation

• Reduce food waste & cost: Reuse what’s already in the pantry before recommending buys.
• Decision fatigue: One-click weekly plan from saved preferences and dietary filters.
• Actionable output: Auto-aggregated shopping list grouped by store section; easy to share.
• Education & health: At-a-glance nutrition helps users pick balanced plans.

Goals

1. Pantry inventory UI with quantities, units, expiry dates, and tags (e.g., “produce”, “spice”).

2. Weekly planner to auto-generate breakfast/lunch/dinner/snacks for N days with dietary constraints.

3. Smart shopping list that:

   • Aggregates ingredients across recipes
   • Converts units (e.g., tsp → g) when possible
   • Marks items fully/partially covered by pantry
   • Supports one-tap “bought” and “substitute” actions

4. Substitution engine (rule-based + ML-ready hooks) offering common swaps (e.g., buttermilk ↔ milk + lemon).

5. Nutrition estimates per recipe and per day; highlight calories, protein, carbs, fat (and allergens if known).

6. Cross-platform: Web (React) and Mobile (iOS/Android/Cordova).

7. Offline-first option: local cache of plan + list with background sync when online.

Non-Goals

• Full grocery delivery integration (can be a follow-up).
• Perfect clinical nutrition accuracy; start with estimates from available data and allow manual edits.

User Stories

• As a user, I can scan or add pantry items with quantity and expiry, so planning uses what I own first.
• As a user, I can auto-generate a 7-day plan based on cuisines, calories target, and dietary flags.
• As a user, I get a shopping list grouped by section (“Produce”, “Dairy”), deduped across recipes.
• As a user, I can accept suggested substitutions when an ingredient is missing or too expensive.
• As a user, I can see nutrition totals per day and adjust the plan.
• As a user, I can share or export the shopping list (copy, PDF, or link).

UX Outline

• Pantry Tab: table/cards with item, qty, unit, expiry, toggle “essential”. Quick add (+), barcode/text input (mobile).

• Planner Tab:

  • “Generate Plan” modal: days, meals/day, calories range, dietary prefs (vegan, halal, nut-free).
  • Grid view by day/meal; drag-to-swap; long-press to replace with similar recipe.

• Shopping List Tab:

  • Grouped sections; badges: Have, Partial, Buy.
  • “Substitute” chip opens suggestions with notes and impact on nutrition.
  • “Share” → copy/print/PDF.

• Recipe Card: nutrition panel; allergens; substitution button.

Data Model (backend python suggestion)

// New entities (pseudo-TS)
PantryItem { id, userId, name, qty: number, unit: string, expiresAt?: ISO, tags: string[] }
MealPlan { id, userId, startDate: ISO, days: number, meals: MealPlanEntry[] }
MealPlanEntry { dayIndex: number, slot: 'breakfast'|'lunch'|'dinner'|'snack', recipeId, servings: number }
ShoppingList { id, userId, items: ShoppingListItem[], planId }
ShoppingListItem { name, qtyNeeded, unit, coveredByPantry: number, substitutes?: Substitute[] , section?: string }
Substitute { name, conversionNote?: string, nutritionDelta?: Partial<Nutrition> }
Nutrition { calories: number, protein: number, carbs: number, fat: number, sodium?: number, fiber?: number }

API (proposed REST under backend/)

POST   /api/pantry                -> create/update item
GET    /api/pantry                -> list items
DELETE /api/pantry/:id            -> remove item

POST   /api/planner/generate      -> body: { startDate, days, mealsPerDay, dietFlags, calorieTarget }
GET    /api/mealplans/:id         -> fetch plan
PATCH  /api/mealplans/:id         -> modify entries (swap/servings)

POST   /api/shopping-list/from-plan/:planId   -> create list
GET    /api/shopping-list/:id
PATCH  /api/shopping-list/:id/items/:idx      -> toggle bought/set substitute

GET    /api/recipes/:id/nutrition  -> computed nutrition
GET    /api/substitutions?name=... -> suggested subs

Algorithm Notes

• Planner: score candidate recipes by (a) pantry coverage %, (b) diet flags, (c) variety (cuisine/ingredient diversity), (d) target calories ± tolerance.
• List aggregation: normalize units to a canonical form per ingredient (simple rules + lookup table).
• Substitutions: start with a static rule table in machine-learning/ (JSON or small DSL), expose hook for future ML ranking.
• Nutrition: basic lookup via recipe metadata; if missing, estimate using ingredient table (extendable dataset).

Mobile & Offline

• Local cache (IndexedDB / SQLite on mobile) for pantry + current plan + list.
• Background sync worker to push local changes when back online.
• Share sheet integration for shopping list.

Telemetry

• Track anonymous events: plan_generated, substitution_accepted, list_item_bought.
• Respect privacy: no PII or ingredient details unless user opts in.

Security & Privacy

• Server-side input validation & auth (tie to existing user model).
• Optional opt-in to sync pantry across devices.

Acceptance Criteria

• Pantry CRUD with quantities, units, expiry, and tags on Web & Mobile.
• Planner generates a 7-day plan that maximizes pantry coverage and respects diet flags.
• Shopping list groups, dedupes, and marks coverage; supports “bought” and “substitute”.
• Substitution suggestions shown with notes; accepting a sub updates list and nutrition.
• Nutrition per recipe and per-day totals visible in UI.
• Export/sharing of shopping list (copy and PDF) works.
• Offline cache lets users view/edit active plan & list without network; sync reconciles later.
• Unit tests for planners, aggregation, and substitutions; e2e smoke for Web; basic mobile tests.
• README updated with screenshots and usage guide.

Implementation Plan (high-level)

1. Backend endpoints + data model (Pantry, MealPlan, ShoppingList, Substitutions, Nutrition).
2. Frontend React views: Pantry, Planner (generate/swap), Shopping List, Nutrition panel.
3. Mobile UI parity (Swift/Kotlin/Cordova screens) with local cache + sync.
4. Substitution ruleset v1 + nutrition lookup table.
5. Unit/e2e tests and documentation.

Open Questions

• Should we allow multiple profiles (e.g., family members with different diet flags)?
• Do we need price awareness per store/region now, or as a follow-up?

[github-actions]

Thank you for submitting this issue. We will look into it as soon as possible.