Done For You Kitchen

Done For You Kitchen is a self-hosted household meal planner built around one idea:

true weekly cost = what you buy - what has a real chance of carrying forward

This repository contains the working Phase 1 foundation, a prompt-free AI weekly planner, a focused custom recipe workshop, and the first Phase 2 kitchen-inventory slice. It is a React Router 8 framework-mode application with strict TypeScript, PostgreSQL, Drizzle ORM, Tailwind CSS, email magic-link authentication, direct Google Vertex AI Express generation, and household-scoped server access.

Current scope

Implemented:

• Two adult users with full access to one household through single-use email magic links
• Configurable household members with appetite multipliers and stable seed identities
• Per-member Usually home or Usually away baselines, plain-language repeating schedules, and direct exact-date changes
• Sunday-to-Saturday week planning with computed dinner serving targets
• Manual recipe entry and recipe display in US customary cooking units, with canonical conversions kept internal
• Prompt-free AI weekly drafting with days-off aware sizing (up to 5 dinners), a repeat-avoidance window covering the last four planned weeks (28 to 84 days), estimated week-start pantry leftovers as a soft preference, same-page dinner review, reversible per-night choices, durable fresh-idea generation for one night, live combined ingredients, and full instructions only after acceptance
• Optional one-off AI recipe drafting from a custom brief
• One household-scoped markdown preference document that guides every weekly generation call, with a safe starter profile and updater audit trail
• Recipe scheduling, replacement, deliberate leftovers, and removal
• Exactly 300 canonical ingredients and one default purchase format per ingredient
• Durable household pantry counts with estimated recipe-use roll-forward, inline weekly inventory controls, package-fit decisions before shopping, a complete generated shopping checklist, native Apple Notes checklist output through Shortcuts, manual correction for skipped or off-plan use, and a reviewed grocery-restock batch that accepts package defaults or actual amounts bought
• PostgreSQL schema, generated Drizzle migration, operator rollback, and idempotent seed command
• Household-scoped queries and mutations, request logging, database-backed sessions, and event logging
• Responsive desktop and phone layouts

Deferred by the requested build order:

• Remaining Phase 2 allocation, persisted shopping checkoffs, Kroger, Instacart, reconciliation, inventory lots, and offline PWA caches
• Phase 3 carryover valuation, cost explanations, scoring, and expiry surfacing
• Phase 4 cost-aware weekly optimization, bench meals, saved swaps, ratings, and rotation

The PWA cache remains deferred because its durable offline contract needs a checkable shopping workflow plus the current week's recipes. The current generated list is derived after each saved count and can create a native Apple Notes checklist through a synced Shortcut, but does not claim in-app persisted checkoffs. The Groceries are home action is an explicit pantry update from a reviewed set of purchases, not a persisted shopping list, receipt, inventory lot, or automatic retailer reconciliation.

Requirements

• Node.js 22.22.0 or newer
• npm 10.9.8 or compatible
• PostgreSQL 15 or newer, including Neon Postgres

The project pins React Router 8.3.0, React 19.2.8, Vite 8.2.1, and all other direct dependencies to exact versions.

Local setup

1. Install dependencies.

   npm install
   

2. Create local environment configuration.

   cp .env.example .env
   

   Replace the database URLs, create a unique secret of at least 32 characters, configure the household member profile JSON, and add a Vertex AI Express API key as GOOGLE_VERTEX_API_KEY. Keep MAGIC_LINK_DELIVERY=console only for local development. AI_RECIPE_MODEL defaults to gemini-3.7-flash through the direct Google provider.

   A linked Vercel project can instead use vercel env pull .env.local --environment=development. Standalone migration and Drizzle commands load .env.local first and then use .env for missing values. The seed also checks an ignored .env.seed.local first so real household profiles can stay separate from runtime configuration.

3. Apply the schema and seed the household plus ingredient reference data.

   npm run db:migrate
   npm run db:seed
   

   The seed command is safe to run again. It updates the canonical manifest and default purchase formats without duplicating the household, users, members, or ingredients. Set HOUSEHOLD_SEED_DRY_RUN=true to execute the full seed transaction and roll it back intentionally before the first production apply.

   HOUSEHOLD_MEMBER_PROFILES_JSON is the preferred member configuration. Each strict profile supplies seedKey, displayName, email, memberType, and appetiteMultiplier. Exactly two adult profiles must have distinct login emails. Keep every non-login member's seedKey stable: it is part of that member's deterministic database identity, so changing it creates a different member instead of renaming the existing one. HOUSEHOLD_ADULT_EMAILS remains available as the four-person legacy fallback when profile JSON is blank.

4. Start the development server.

   npm run dev
   

5. Open http://localhost:5173. Request a link for one of the two seeded adult emails. In console delivery mode, the sign-in screen exposes a development-only preview link. The link opens a confirmation screen and is consumed only after confirmation.

This is the beginning of the README. Read the rest at the original. Read the full README ↗