# 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 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 ### Family Members | Member | Role | Mushroom Preference | |--------|------|-------------------| | Adult 1 | Adult | Does NOT like mushrooms | | Adult 2 | Adult | Likes mushrooms | | Child 1 | Child | Does NOT like mushrooms | | Child 2 | Child | OK with mushrooms | ### Dietary Constraints - 3 of 4 family members do NOT like mushrooms - No allergies ### Preference Signals - "Never suggest this ingredient" flags (per family, not per member) - Per-meal ratings (1-5 stars, per member) - 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 all adult family members containing: - All 7 meals listed with images - Each meal has: "View & Vote" link to web approval page - Email does NOT auto-approve on link click 3. Approval page flow (Web UI): - Adult clicks email link → lands on confirmation page - Page shows meal details, image, ingredients, estimated cost - Adult clicks "Approve" or "Deny" - Denial requires selecting a reason - Vote is recorded per-member (not per-household) 4. Approval handling: - If majority of adults approve → meal confirmed - If any adult denies → meal swapped with alternative suggestion - Denial reason is recorded for learning - Explicit deadline: 48 hours from email send - After deadline: meals with insufficient responses auto-expire and are excluded 5. After approval period: - Final meal plan locked - Shopping list generated - Recipes made available in web UI ### Approval Token Security - Each email contains a unique, single-use token per family member - Tokens expire after 72 hours - Tokens can only be used once (marked USED after voting) - Email links lead to a confirmation page; actual vote is a POST --- ## 8. Technical Constraints ### Self-Hosting Requirements - Must run on local infrastructure (homelab, NUC, Synology, etc.) - Remote access via reverse proxy with VPN or TLS - Primary access: local network only (VPN required for remote) ### Authentication & Authorization - **Admin endpoints** (`/api/admin/*`): VPN-only access - **Family web UI**: Session-based authentication (simple username/password) - **Email approval links**: Token-based, single-use, time-limited - No JWT; no OAuth ### Lucky California Integration - **URL**: https://luckysupermarkets.com (verified) - 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 - Accessible: includes alt text for images, works with screen readers ### External Dependencies | Service | Purpose | Required | |---------|---------|----------| | SendGrid | Transactional email | Yes | | luckysupermarkets.com | Grocery scraping | Yes | | Recipe websites | Recipe images | Yes | | AI Image API (optional) | Fallback image generation | No | --- ## 9. Accessibility (WCAG 2.1 AA) ### Web UI - All interactive elements keyboard accessible - Color contrast ratio ≥ 4.5:1 for normal text - Form inputs have visible labels - Error messages are descriptive and associated with inputs - Skip navigation links provided ### Email - HTML emails include meaningful alt text for all images - Plain text version provided as fallback - Links are descriptive (not "click here") - Font sizes are readable (minimum 14px equivalent) --- ## 10. Data Retention ### Stored Data - All recipes (scraped and manually added) - Meal plans (weekly history) - Per-member votes and denial history - 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) --- ## 11. 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. **Explicit approval rate**: >80% of proposed meals receive explicit approval (not silence) 5. **Learning**: After 4 weeks, system should not propose previously denied meals --- ## 12. 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