Public Access
admin
0c5b0aa5ed
- SPEC.md: project specification and goals - ARCHITECTURE.md: system design and component descriptions - database-schema.md: PostgreSQL schema with all tables - implementation-plan.md: 12-phase implementation guide - RUNNING.md: deployment and troubleshooting guide - ORIENTATION.md: context compaction recovery guide - README.md: project overview and quick start Family profile: 2 adults, 2 children. Mushroom avoidance for 3/4. Approval workflow: email proposals, one denial swaps meal. Tech stack: FastAPI, PostgreSQL, React, Playwright, SendGrid.
178 lines
6.1 KiB
Markdown
178 lines
6.1 KiB
Markdown
# 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
|