Meal-Planner/docs/ORIENTATION.md

Meal Planner - Orientation Guide

This document is the first stop for any agent resuming work on this project after context compaction. Read it before doing anything else.

---

Project Overview

MealPlanner is a self-hosted meal planning system for a family of 4 (2 adults, 2 children) that integrates with Lucky California grocery store to source ingredients from weekly sales, sends meal proposals via email, generates shopping lists, and learns from feedback.

Key Problem Being Solved

The family has been using meal kit services (Blue Apron → EveryPlate → HungryRoot → Sunbasket) which suffer from:

• 3x ingredient markup in cost
• Repetitive meals and sauces
• Forcing app login to manage meal selection
• No home pantry integration

Current Status

Phase: Post-adversarial-review fixes applied. Ready for verification.

Adversarial Review Completed: 2026-05-04

• All consensus blockers (§1.1 - §1.8) addressed
• All high-risk gaps (§2.1 - §2.8) addressed
• Key fixes applied:
  • Recipe-ingredient: JSONB only (removed join table)
  • Family member: Added family_member table for per-voter tracking
  • Approval flow: Redesigned with confirmation page + POST + per-voter tokens + TTL
  • Auth: VPN-only for admin endpoints, session-based for family web UI
  • Schema: ENUMs, CHECKs, CITEXT for ingredients, ISO day_of_week (1=Mon)
  • Lucky URL: Fixed to https://luckysupermarkets.com
  • Docker: Hardened (no direct port exposure to backend/frontend)
  • Alembic: Configured with migration policy

---

Architecture Summary

User (email) ──► SendGrid ───────────────────────────────┐
User (web)  ───► React UI ──► nginx ──► FastAPI ──────────┼──► PostgreSQL
                          │                             │
                          └──► Lucky CA scraper ──┘
                              (luckysupermarkets.com)

Services (Docker Compose)

• backend: FastAPI Python app (port 8000, internal only)
• frontend: React + Tailwind (port 3000, internal only via nginx)
• db: PostgreSQL 15 (internal only)
• nginx: Reverse proxy with SSL (ports 80/443)

Tech Stack

• Backend: Python 3.11, FastAPI, SQLAlchemy 2.0, Alembic
• Frontend: React 18, TypeScript, Tailwind CSS, React Query, Vite
• Database: PostgreSQL 15 with ENUMs and CITEXT
• Scraping: Playwright, BeautifulSoup
• Email: SendGrid
• Hosting: Docker Compose, nginx

---

Family Profile

Household

• 2 adults, 2 children
• 3 of 4 members do NOT like mushrooms
• No allergies
• Goals: Calorie, budget, and health conscious; tasty but not 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

Approval Workflow (REDESIGNED)

1. System generates 7-day meal plan (Sunday)
2. Email sent to all adults with meals, images, approval page links
3. Email link → confirmation page (GET, not auto-approve)
4. Adult clicks Approve/Deny → POST with reason
5. Per-member token (single-use, 72h TTL)
6. Majority approve → meal confirmed; any deny → swap
7. After approval → shopping list generated

---

Database Schema Highlights

Core Tables

• family_profile - Household configuration with household_size CHECK
• family_member - Individual family members with email, role, mushroom preference
• recipe - Recipes with JSONB ingredients (not join table)
• ingredient - Master list with name_lower (CITEXT for case-insensitive matching)
• meal_plan - Weekly plan with ISO day_of_week (1=Mon, 7=Sun)
• meal_plan_item - Individual meal with approval status
• meal_plan_vote - Per-member votes (one vote per member per meal)
• approval_token - Single-use tokens with TTL and status tracking
• home_pantry - Family's on-hand ingredients
• feedback - Ratings, denial reasons, never-suggest flags
• grocery_item - Scraped Lucky California items with FK to ingredient
• scrape_log / email_log - Operation history

Key Relationships

• family_profile 1:N family_member
• family_profile 1:N meal_plan
• family_member 1:N meal_plan_vote (per-voter tracking)
• recipe 1:N meal_plan_item
• meal_plan 1:N meal_plan_item
• meal_plan_item 1:N meal_plan_vote
• meal_plan_item 1:N approval_token
• grocery_item → ingredient (FK)

---

Implementation Phases

Phase	Description	Status
1	Infrastructure (Docker, PostgreSQL, FastAPI, React, nginx)	Complete
2	Database & Models (SQLAlchemy models, Alembic migrations)	Post-review fixes applied
3	API Endpoints (CRUD, meal plans, shopping list, feedback)	Not Started
4	Lucky California Scraper (weekly ad, Playwright)	Not Started
5	Recipe Engine (CRUD, tagging, search)	Not Started
6	Meal Planner Engine (generation algorithm, substitutions)	Not Started
7	SendGrid Email Integration	Not Started
8	Web UI - Core (Dashboard, Meal Detail, Approval, Pantry)	Not Started
9	Web UI - Feedback (Feedback Portal, Learning)	Not Started
10	Shopping List & Print	Not Started
11	Image Strategy (scraped + AI fallback)	Not Started
12	Polish & Future (variety analysis, budget tracking)	Not Started

---

Environment Variables

# Database
DATABASE_URL=postgresql://mealplanner:password@db:5432/mealplanner
POSTGRES_PASSWORD=secure_password

# SendGrid
SENDGRID_API_KEY=SG.xxx

# Family
FAMILY_EMAIL_1=user@example.com
FAMILY_EMAIL_2=spouse@example.com

# Scraping
LUCKY_CA_URL=https://luckysupermarkets.com

# AI Images (optional)
AI_IMAGE_ENABLED=false

# Auth
SECRET_KEY=change-me-in-production

---

Next Steps

IMMEDIATE: Verify skeleton with verification matrix

docker compose config
docker compose build backend
docker compose build frontend
docker compose up -d db
docker compose run --rm backend python -c "from app.main import app; print(app.title)"
docker compose run --rm backend alembic upgrade head
docker compose run --rm frontend npm run build

If any of these fail, fix before proceeding.

After Verification

1. Phase 2: Implement real API endpoints (not placeholders)
2. Phase 3: Connect database models to endpoints
3. Phase 4: Spike Lucky California scrape (before committing to full schema)

---

Current Git State

git log --oneline
624b516 docs: update ORIENTATION.md for Phase 1 complete
1328ec3 feat: add Phase 1 infrastructure skeleton
0c5b0aa docs: add complete project documentation

Pending commit: All adversarial review fixes (models, schema, docker-compose, docs updates)

---

Important Conventions

Code Style

• Python: Black formatter, isort for imports
• TypeScript: Prettier, ESLint
• No comments unless explaining non-obvious logic

Git Commits

• Conventional commits: feat:, fix:, docs:, refactor:, test:
• One logical change per commit where possible

API Design

• RESTful endpoints with proper HTTP methods and status codes
• Pydantic schemas for request/response validation
• Email approval links use GET → confirmation page → POST
• Per-voter tokens, not shared household tokens

Database

• Always use UUIDs for primary keys
• Timestamps with timezone (TIMESTAMPTZ)
• Use ENUMs for status fields (not loose VARCHAR)
• Use CITEXT or lowercase-on-write for name matching

Testing

• Write unit tests for services (pytest)
• Integration tests for API endpoints
• Frontend: component tests with React Testing Library

---

Known Issues / Open Questions

1. Lucky California scraping: Feasibility not yet spiked. URL is luckysupermarkets.com.
2. AI image generation: Config flag to enable/disable. Disabled by default.
3. WhatsApp integration: Planned for future via Twilio. Out of scope for MVP.
4. Planned scheduler: APScheduler with --workers 1 to avoid duplicate fires.

---

Contact / Context

• Primary user: Peter (tech-savvy, hosts the system)
• Wife: Non-technical, will use web UI and email
• Children: 2, eating habits vary (one OK with mushrooms)

Last updated: 2026-05-04 (post adversarial review fixes)