Public Access
docs: add complete project documentation
- 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.
This commit is contained in:
+177
@@ -0,0 +1,177 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user