Meal-Planner/docs/SPEC.md

Meal Planner - Project Specification

1. Overview

Project Name: MealPlanner Type: Self-hosted meal planning system Core Functionality: Weekly meal plan generation that integrates with Lucky California grocery sales, sends approval requests to family members via email, generates shopping lists, and learns from feedback. Target Users: A family of 4 (2 adults, 2 children) seeking to optimize meal planning for cost, health, and variety.

---

2. Problem Statement

Current meal kit services (Blue Apron → EveryPlate → HungryRoot → Sunbasket) suffer from:

• Escalating costs (3x ingredient markup)
• Repetitive meals and sauces
• Forcing users to log into apps to manage meal selection
• No offline pantry integration

Desired Solution: A self-hosted system that:

• Sources ingredients from local grocery store (Lucky California) sales and in-season products
• Proposes meals via email with approval workflow
• Generates actionable shopping lists
• Incorporates existing home pantry items
• Learns from family feedback over time

---

3. Goals

Primary Goals

1. Weekly Meal Planning: Automatically generate a 7-day meal plan each week
2. Grocery Integration: Scrape Lucky California weekly ads and product catalog for sales/in-season items
3. Family Approval Workflow: Send email to both adults with meal proposal, image, and details; one denial swaps the meal
4. Shopping List Generation: Create weekly shopping list grouped by Lucky California aisles, highlighting sales
5. Pantry Integration: Allow users to specify items they have at home to incorporate into meal suggestions
6. Web UI: Modern interface for non-technical family members to interact with meals, feedback, and recipes
7. Recipe & Image Generation: Display meal images and printable recipes

Secondary Goals

1. Feedback Learning: System learns from "never suggest", ratings, and denial reasons
2. Variety Analysis: Detect when meals fall into similar rhythms (same sauces/ingredients)
3. Budget Optimization: Track and optimize meal costs per serving
4. WhatsApp Integration: Future expansion via Twilio (out of scope for initial build)

---

4. Non-Goals (Out of Scope)

• Actual online ordering/payment at Lucky California
• Native mobile apps (responsive web UI only)
• Recipe parsing from personal recipe collections (Paprika, etc.)
• AI image generation as primary source (scraped images first)
• Multi-language support
• Nutrition tracking beyond high-level calorie awareness

---

5. User Stories

As a family member, I can:

• Receive weekly email with proposed meals for the week
• View meal details including: name, image, ingredients, cook time, servings
• Approve or deny a meal with optional feedback reason
• Access the web UI to adjust home pantry items
• View printable recipe cards
• Provide feedback on meals ("Loved it", "Too bland", "Never again")

As the system administrator, I can:

• View scraping logs and debug failed scrapes
• Adjust family profile settings (dietary restrictions, household size)
• See meal plan approval history
• Monitor system health via logs

---

6. Family Profile

Household

• 2 adults, 2 children
• Calorie, budget, and health conscious eating
• Food should be tasty but not overly expensive

Dietary Constraints

• One adult likes mushrooms
• One child is OK with mushrooms
• Two adults and one child do NOT like mushrooms
• No allergies

Preference Signals

• "Never suggest this ingredient" flags
• Per-meal ratings (1-5 stars)
• Denial reasons (too expensive, looks boring, contains disliked ingredient, etc.)
• Home pantry items to incorporate

---

7. Approval Workflow

Weekly Flow

1. System generates 7-day meal plan based on:

   • Lucky California sales and in-season items
   • Family dietary constraints (no mushrooms for 3/4 members)
   • Budget constraints
   • Variety requirements (avoid sauce/ingredient repetition)
   • Home pantry items to use

2. Email sent to both adults containing:

   • All 7 meals listed with images
   • Each meal has: Approve / Deny buttons (via email links or web UI)
   • Denial requires a reason selection or free-text

3. Approval handling:

   • If both approve OR no response → meal confirmed
   • If either denies → meal swapped with alternative suggestion
   • Denied meals logged for learning

4. After approval deadline:

   • Final meal plan locked
   • Shopping list generated
   • Recipes made available in web UI

---

8. Technical Constraints

Self-Hosting Requirements

• Must run on local infrastructure (homelab, NUC, Synology, etc.)
• Remote access via reverse proxy (Caddy or nginx)
• No external cloud services except SendGrid for email

Lucky California Integration

• Primary: Scrape weekly ad and product catalog
• Store scraped data locally
• Respect robots.txt and rate limiting
• Fallback: Manual sale input if scraping fails

Email

• SendGrid for transactional email
• HTML email templates with meal images
• Plain text fallback for email clients that block images

---

9. Data Retention

Stored Data

• All recipes (scraped and manually added)
• Meal plans (weekly history)
• Approval/denial history with reasons
• Feedback (ratings, flags, pantry items)
• Scraped grocery data (weekly refresh)

Retention Period

• Meal plans: 12 weeks rolling
• Feedback: Indefinite (for learning)
• Scraped grocery data: 2 weeks (to compare week-over-week)

---

10. Success Metrics

1. Adoption: Family consistently uses the system weekly
2. Meal variety: No more than 2 meals/week share the same sauce or primary protein
3. Cost efficiency: Average cost per serving within 150% of equivalent grocery-store meal
4. Approval rate: >80% of proposed meals approved without changes
5. Learning: After 4 weeks, system should not propose previously denied meals

---

11. Future Considerations

• Twilio WhatsApp integration for wife who prefers messaging
• Direct Lucky California online ordering
• Meal kit comparison (show cost difference vs. meal kit services)
• Nutritional tracking (macros, sodium, etc.)
• Grocery price history and trend analysis