# Recipe Site

> A social cooking network that helps friends and families cook better using trusted, real-world kitchen signals

- HTML version: https://robbiepalmer.me/projects/recipe-site
- Status: in_progress
- Started: 2026-02-14
- Source code: https://github.com/Robbie-Palmer/personal-site
- Live demo: https://robbiepalmer.me/recipes
- Technologies: GitHub, React, Next.js, Mise, Tailwind CSS, Turbopack, pnpm, Vitest, CodeRabbit, Terraform, Cloudflare Pages, Claude Code, Husky, GitHub Actions, Terraform Cloud, GitHub Secrets, shadcn/ui, Fuse.js, Renovate, Cloudflare DNS, Cloudflare Images, Cloudflare Terraform Provider, CodeQL, TypeScript, Shortcut, CLA Assistant, PostHog, DVC, cooklang-rs, OpenRouter, Better Auth, Cloudflare Workers, Neon, Hono, Drizzle, Hyperdrive, Google OAuth, GitHub OAuth, Greptile, Codex, Trivy, SonarQube, zizmor, actionlint, OpenTelemetry, Cloudflare Workflows, Cloudflare R2, Cloudflare Access, PostgreSQL, Doppler, age, TanStack Query, TFLint, Knip, OpenSSF Scorecard, Gitleaks, typos, Slack, Spectral, OpenAPI, oasdiff

# Vision

Help friends and families cook more often and more successfully by learning from what their kitchens actually do.

Recipe Site began as a digital replacement for our handwritten recipe book, but a searchable collection is no
longer a sufficient product vision. The larger opportunity is a **social cooking network** whose public activity
creates a compounding knowledge base and whose household context makes that knowledge useful. It is built from
five connected models:

* **A public cooking commons** lets people publish recipes and adaptations, follow cooks, share outcomes, and
  discover what is actually being cooked—not merely what attracts clicks or reviews.
* **A recipe graph** records provenance, exact versions, forks, and the adaptations that make a recipe work in a
  particular home while allowing evidence to accumulate across related versions.
* **A household kitchen twin** is a deliberately incomplete, useful model of the people eating, their dietary
  constraints, available equipment and ingredients, planned meals, portions, leftovers, and recent cooking.
* **A trust graph** connects households, friends, and cooks so public evidence can be weighted by whose judgement
  and circumstances are personally relevant.
* **A taste and utility graph** keeps likely enjoyment separate from practical, contextual fit. It learns from
  recipes people actually cook, repeat, adapt, and abandon, allowing somebody to discover useful "taste
  neighbours" and communities beyond the people they already know without turning frequency into a universal
  score.

The network cannot compensate for a weak personal product. People should first choose Recipe Site because it is
an excellent way to run their own food lifecycle: **discover or capture → plan → shop or order → stock → cook →
eat → store leftovers → repeat or adapt**. Social value should emerge from those useful actions rather than ask
people to perform extra engagement work. This is why Tandoor is such a serious competitor: its breadth raises the
single-player baseline that must be met before Recipe Site's network effects matter.

Together they turn ordinary actions into useful evidence. A five-star review says that somebody liked a recipe;
repeated cooks, successful adaptations, empty plates, and a recommendation that a friend actually planned and
made show much more. The product should learn from actions people already take—planning, shopping, cooking,
adapting, and repeating—rather than demand extra logging or engagement. Those outcomes can answer practical
questions: What will work for this household tonight? Which exact version succeeds most often? What can we cook
with what is here? Who we trust has actually made this—and made it again?

Taste is only one dimension of value. A spectacular five-star dish might be cooked once a year; a merely very
good meal might become a weekly staple because it is fast, affordable, predictable, batchable, accepted by the
household, and compatible with somebody's energy, mobility, training, or work pattern. A stay-at-home parent, an
entrepreneur, an athlete, and somebody with limited mobility may all enjoy the same food while needing different
recipes day to day. The graph should preserve both truths: **How good was it?** and **How well did it fit this
life, household, and occasion?**

The product should close the loop from **recommended → saved → planned → shopped → cooked → adapted → repeated**.
When somebody chooses to make part of that loop public, it should strengthen the shared recipe and cooking graph:
better recipes earn behavioural proof, useful adaptations retain attribution, cooks find people worth following,
and discovery improves. That drives more cooking, which creates more evidence, which improves the next decision.
Household state supplies local context—what is available, who is eating, and what tends to work—while ordinary
visibility controls keep irrelevant domestic details out of the public graph.

The discovery promise is: **Someone who eats like you tried something new and loved it. Maybe you should too.**
That combines similarity with exploration. It should help people escape their existing social food bubble, not
turn inferred taste into a narrower one.

We have used a handwritten recipe book for years. It has genuine UX strengths: no lock screens, no risk of water
or food damage to an expensive device, easy to prop open on a counter. But the limitations are severe enough
that we lose recipes, avoid making changes, and work around the format constantly. A digital version should
preserve what works about the physical book (glanceable, kitchen-friendly) while eliminating everything that
doesn't.

# Problem Statement

A handwritten recipe book creates friction at every stage of the recipe lifecycle:

**Collecting recipes is inconvenient.** Adding a recipe requires being physically with the book and having time
to transcribe by hand. Recipes discovered online, from friends, or from social media (saved Instagram videos,
bookmarked websites, Facebook posts) pile up across different platforms and many are lost. The barrier to entry
is too high for casual additions.

**Editing is destructive.** Adapting a recipe often means destroying the original page and rewriting entirely —
there's no room for new instructions, and scoring out old text makes the page illegible. This discourages
experimentation. Recipes need multiple attempts before settling on a final form, but the cost of each iteration
is a full page rewrite.

**Finding recipes is slow.** Locating a specific recipe means flicking through every page. There's no search,
no filtering by cuisine or cooking time, no way to answer "what can I make in under 30 minutes?" without
reading every entry.

**Discovering food is noisy and self-reinforcing.** Today we depend on celebrity chefs and editorial brands,
friends or family doing the work of writing out what they cook, keyword search that assumes we already know what
we want, or social-media creators rewarded when a video holds attention. Those channels can inspire, but they do
not usually observe whether a recipe was cooked successfully or became part of somebody's rotation. Our existing
relationships and viewing history can also keep us inside the cuisines and creators we already know.

**Ratings collapse different kinds of value.** "Five stars" can mean delicious, impressive, easy, reliable,
good for children, worth the effort, or simply successful on one occasion. It cannot explain why somebody loved
a recipe but never repeated it, or why a less exciting dish became foundational to their week. Without actual
planning and cooking behaviour, discovery cannot distinguish aspiration from practical fit.

**Shopping is manual transcription.** To shop for a recipe, we manually copy ingredients from the book into
a notes app on our phones to use as a checklist in the supermarket. This is tedious, error-prone, and
completely unnecessary with digital data.

**Portioning is error-prone.** Scaling recipes up or down requires mentally converting every ingredient amount.
When ingredients appear mid-recipe in the instructions, it's easy to forget to convert them and use the
amount on the page — resulting in failed dishes. The page should display the truth of what you want, not
require mental arithmetic.

**Unit confusion.** We collect recipes from different countries with different measurement systems — cups,
Fahrenheit, metric. These often don't match our measuring utensils and cause confusion during cooking.

**The book can be lost.** A single physical copy with no backup. If it's lost, damaged, or destroyed,
years of collected recipes are gone.

These aren't just our problems, but competitors now solve most of them individually. The
[competitor analysis](#competitor-analysis) below shows that Tandoor is already an excellent collection manager
and Samsung Food already connects community, planning, shopping, pantry state, and cooking feedback. Recipe
Site is justified as more than a personal build only if it connects these jobs differently: trusted
relationships, a growing public cooking graph, household context, recipe lineage, and observed cooking behaviour
must produce better decisions than a generic feature-rich manager or a public review feed.

# User Stories

**For the cooks (us):**

* I want to search and filter recipes by cuisine, ingredient, or cooking time, so I can quickly decide what to make without flicking through every page
* I want to adjust portion sizes and see all ingredient quantities update automatically, so I never miscalculate when scaling a recipe
* I want to convert between measurement units (metric, imperial, cups), so recipes from any country work with my utensils
* I want a cooking mode with large text and step-by-step progression, so I can follow a recipe in the kitchen without fiddling with a device
* I want inline timers in recipe steps, so I don't need to context-switch to a separate timer app or shout at a voice assistant
* I want to save recipes as drafts without worrying about perfection, so I actually capture recipes when I find them instead of losing them
* I want to edit recipes non-destructively, so I can iterate and improve without losing the original
* I want to generate shopping lists from one or more recipes, so I never have to manually transcribe ingredients again
* I want to hand a finalized list to my preferred supermarket or delivery service, so planning can become an
  actual basket without entering every item again
* I want nutrition calculated from the recipe version, servings, and meals I already cook, so useful guidance
  does not require maintaining a separate food diary
* I want nutritional suggestions while choosing, planning, shopping, or adapting a meal, so insight arrives when
  I can act on it rather than as a score after the fact
* I want deliciousness and everyday usefulness represented separately, so a special-occasion favourite and a
  practical staple can both be valued for what they are
* I want recommendations to account for the current occasion, available time, energy, equipment, budget, and
  household—not assume that one global ranking describes what is useful today
* I want to access my recipes from any device, anywhere, so I'm not dependent on being physically near a book

**For friends and family:**

* I want to browse their recipes on a shared website, so I can try dishes they've recommended
* I want to share a link to a specific recipe, so I can send it to someone who asks "how do you make that?"
* I want to recommend a specific version with a personal note, so context such as "the children ate this" or
  "this worked without onion" travels with it
* I want to know which recipes people I trust actually cook and repeat, so recommendations reflect behaviour
  rather than only ratings or reviews
* I want to see whether a recommendation was saved, planned, cooked, or adapted when the recipient chooses to
  share that outcome, so useful recipes spread through real use
* I want our household's meal plan, shopping, pantry, portions, and leftovers to stay coordinated, so cooking is
  a shared activity rather than one person's administrative burden

**For cooks contributing publicly:**

* I want to publish recipes and adaptations with provenance, so other people can build on them without erasing
  authorship or confusing their version with mine
* I want to see how often each version is actually cooked, repeated, or adapted, so feedback reflects real use
  as well as what people choose to write
* I want public cooking activity to help the right recipes and cooks become discoverable, so contribution creates
  value beyond my immediate household
* I want simple control over whether an individual cooking event is household-only, shared with connections, or
  public, so I can contribute useful evidence without publishing irrelevant household details

**For people discovering what to cook:**

* I want to find cooks whose demonstrated tastes resemble mine, even when I do not already know or follow them,
  so my discovery pool grows beyond celebrity chefs, influencers, and my immediate social circle
* I want to understand why a recipe crossed into my feed—such as "people who repeat your favourites loved this"—
  so personalization is useful and inspectable
* I want some recommendations to bridge from familiar tastes into a new cuisine, ingredient, or technique, so
  similarity helps me explore rather than trapping me in a tighter filter bubble
* I want to form or join communities around shared cooking behaviour as well as declared interests, so groups
  reflect food people make and value rather than whoever accumulated the most followers

**For people building a personal collection:**

* I want to add recommended recipes to my own collection, so I can personalize and adapt them
* I want to favorite and rank recipes, so my most-loved dishes are easy to find
* I want to track what I've cooked and when, so I can identify popular vs neglected recipes and avoid repeating meals too frequently
* I want my adaptations to retain their source and outcomes, so improvements can travel without flattening every
  household's version into one supposedly canonical recipe

# Product Today

The first usable recipe list has grown into a multi-user cooking product. Delivery did not follow the
original sequence of MVP followed by five discrete phases: authentication and persistence created critical
paths, while agentic coding made it practical to advance independent surfaces in parallel. The product now
includes:

## Recipe Box, Discovery & Editing

* **Database-backed recipe boxes** with public, private, and household visibility
* **Search and tri-state filters** across cuisines, ingredients, time, and required equipment
* **Structured Cooklang recipes** with grouped ingredients, cookware, attribution, and live editing preview
* **Serving adjustment** that scales ingredient quantities both in the list and inside instruction text
* **Configurable metric, US, and UK units**, with browser-persisted preferences
* **Public profiles and discovery feeds**, including cook follows and a dedicated Following feed

## Cooking

* **Large-text, step-by-step cooking mode** with previous/next navigation and an up-next preview
* **Inline and custom timers** that persist while navigating, support several concurrent timers, and use the
  Screen Wake Lock API where available
* **Ingredient checklists and equipment lists** alongside the instructions
* **Cooking sessions and insights** recording starts, completed meals, recently cooked recipes, and variety

## Shopping, Planning & Kitchen

* **Weekly meal planning** across breakfast, lunch, and dinner slots
* **Aggregated shopping lists** that merge recipe quantities, support free-form extras, sort into aisles, and
  subtract ingredients already in stock
* **Pantry, fridge, and fresh-stock tracking** with recipe matching based on ingredients on hand
* **Shared household pantry state** so members work from the same stock picture

The meal plan and shopping list currently persist in the browser and synchronize across tabs, not across
devices or household members. That boundary is now more important than adding another planner view.

## Capture, Accounts & Collaboration

* **Manual recipe creation and editing**, plus imports from Cooklang text/files and schema.org recipe URLs
* **Photo-to-recipe ingestion** backed by a durable Cloudflare Workflow and an extract → normalize →
  canonicalize → finalize pipeline, with an editable result rather than blind publishing
* **Google and GitHub login**, onboarding, profile, security, diet, household, and unit settings
* **Household invitations and administration**, recipe sharing, direct recommendations, and in-app
  notifications with actionable states
* **Diet-aware browsing and planning** using presets and ingredient exclusions
* **Portable Cooklang, Markdown, and schema.org Recipe JSON representations** rather than a closed data silo

These are meaningful pieces of the larger vision, but they do not yet form the social learning loop. Public
recipes and profiles create the beginnings of a commons; follows shape discovery; recommendations are
person-to-person hand-offs; cooking sessions record starts and completions; and the pantry represents household
state. The product cannot yet connect those facts to say that a recommendation led to a completed meal,
distinguish a one-off cook from a household staple, publish well-defined behavioural proof, or carry the outcome
of an adaptation back through its lineage. That is the most important product gap—not another isolated feature
checkbox.

Discovery also stops at public recency and the explicit follow graph. The system cannot yet identify cooks with
similar demonstrated tastes, explain an affinity-based recommendation, suggest an emerging community, or
deliberately trade familiarity for exploration.

The personal loop is also incomplete. Plans and shopping are not yet account-backed, shopping stops before a
retailer basket, pantry updates are manual, leftovers are not represented, and nutrition is not derived from
recipes or completed cooks. Closing those gaps is prerequisite work for the social graph because it both makes
the product worth returning to and produces higher-quality outcome data.

# Roadmap

The roadmap is organized around dependencies and product gaps, not release phases. Critical-path work is
sequenced; the other tracks can move concurrently when they do not contend for the same data model or user
journey.

## Critical Path

### Complete the Personal Food Lifecycle

Make the single-player journey exceptional before expecting social features to retain anyone. Connect capture
and discovery to server-backed plans, synchronized shopping, pantry and freezer state, cooking sessions,
portions, leftovers, and repeat cooking. A person should get clear value from every stage even if none of their
friends has joined yet.

Treat retailer hand-off as part of the journey, not permanently out of scope. Once the canonical shopping list
is server-backed, integrate one retailer or grocery intermediary deeply enough to validate ingredient-to-product
matching, quantities, substitutions, availability, and basket transfer. Prefer providers with broad coverage or
stable partner interfaces before maintaining many retailer-specific adapters. Corrections made during product
matching can improve the ingredient ontology and future lists.

Nutrition should also fall out of normal use. Calculate recipe and serving nutrition from structured ingredients;
when somebody completes a cook, infer the meal from the version and portion already selected, asking only about
meaningful deviations. This is approximate decision support, not clinical intake measurement. Its job is to make
the next plan, shop, adaptation, and meal better without creating another daily logging obligation. Barcode
scanning does not solve this if users must assemble individual products into a meal, and meal photography does
not solve it if every result requires full human reconstruction.

### Close the Social Cooking Loop

Define a small, durable event model connecting recommendations, saves, plans, shopping, cooking sessions,
adaptations, repeats, and lightweight outcomes. Move meal plans and shopping lists from browser-only storage to
account or household state so those events describe one continuous journey rather than unrelated activity in
different clients.

Give each event an explicit audience—personal, household, connections, or public—and derive public aggregates
without conflating them with household coordination. A recommendation should be traceable from sender to outcome
when both sides choose to share it. Counts must distinguish a recipe view, save, plan, cook-mode start, completed
meal, repeat cook, and adaptation rather than collapsing all engagement into popularity.

### Turn Public Activity Into a Flywheel

Expand the public feed beyond newly published recipes to the high-value events people choose to share: completed
cooks, repeat cooks, attributed adaptations, and deliberate recommendations. Recipe pages should show an
evidence ladder such as "made 128 times," "54% made it again," and "three cooks you follow made this," with exact
definitions and enough sample context to avoid false precision.

Public discovery supplies reach and liquidity; the trust graph re-ranks that evidence for the individual; the
household twin filters it through present constraints. Contributors get useful feedback and attribution, users
get better discovery, and each real cooking outcome improves the graph for the next person. Text, photos,
comments, and reviews add valuable context, but actual cooks, repeats, and adaptations are the stronger ranking
signals.

Combine global and personal evidence rather than choosing one. Public aggregates reveal recipes that work beyond
one social circle; relationship-aware views reveal who cooked a recipe, who made it again, which fork they used,
what they changed, and whether it worked for a relevant diet or piece of equipment. Preserve deliberate personal
recommendations and notes; do not replace them with an opaque feed.

Samsung Food already exposes communities, "Made It" actions, ratings, and reviews. Its own documentation notes
that editing creates a tweak whose ratings and reviews are then detached from the original. Recipe Site should
make lineage the organizing principle, so evidence stays attached to the exact version it describes and can
roll up carefully across related versions.

### Discover Through Taste Neighbours

Model two related but distinct questions: **Will I enjoy this?** and **Will this work for me now?** Taste affinity
can learn from explicit deliciousness feedback, shared favourites, cuisines, ingredients, and adaptations.
Practical fit can learn from plan-to-cook conversion, repeat cadence, actual effort, batch and leftover use,
shopping corrections, household acceptance, and lightweight reasons for abandoning a plan. Repetition is useful
evidence for both models, but it is proof of neither on its own.

"Taste neighbour" should remain the human-facing discovery idea: somebody whose demonstrated palate makes their
successful exploration relevant to you. Context then re-ranks that bridge for the present job. A useful
weeknight taste neighbour may differ from a baking or dinner-party neighbour, and somebody with similar taste
may have a completely different budget, schedule, household, equipment, energy, training load, or accessibility
need. Dietary and accessibility constraints must not be mistaken for preference or inferred identity.

Candidate discovery should deliberately mix four sources:

1. cooks and households the user explicitly follows;
2. people with similar demonstrated taste, whether or not they are socially connected;
3. communities organized around cuisines, constraints, techniques, goals, or emerging behaviour; and
4. controlled exploration outside the current cluster.

Rank for predicted cooking value, not predicted viewing time or one blended score. Explain both the taste bridge
and the practical evidence: "taste neighbours who loved the same three dishes loved this Georgian stew," "cooks
with your weekday pattern keep this in rotation," or "highly rated for special occasions; rarely repeated."
Track whether the suggestion is saved, planned, cooked, repeated, or dismissed, and capture extra feedback only
when the behaviour is ambiguous. Community suggestions can come from the graph, but joining, identity, and
governance should remain human choices rather than silently assigning people to algorithmic cohorts.

Discovery should expose several kinds of value instead of replacing five stars with frequency. A reliable
Tuesday staple, a high-effort celebration dish, and a useful batch-cooking base can all succeed on different
axes. Let people choose the occasion and show separate evidence for enjoyment, effort, reliability, and repeat
use wherever the sample supports it.

Prevent the taste graph from becoming a stronger bubble by reserving space for adjacent novelty, allowing users
to tune familiarity versus exploration, and testing whether recommendations broaden the cuisines, ingredients,
and techniques people actually cook—not merely those they view.

### Build the Household Kitchen Twin

Join people and dietary constraints, recipes and lineage, pantry and freezer state, equipment, plans, shopping,
servings, cooking sessions, and leftovers into one operational household model. This does not require perfect
inventory accounting. It requires enough current state to coordinate work and make honest, context-aware
suggestions—with confidence and provenance visible whenever the state is inferred.

The twin must remain practical rather than pretending to be a perfect inventory ledger: make state easy to
correct, distinguish observed facts from estimates, and never turn incomplete tracking into false certainty.
Audience controls are necessary product hygiene, not the product thesis.

### Trustworthy Iteration and Lineage

Add user-visible version history, comparison, and restore for recipes now that Postgres—not git—is the source
of truth. Then add recipe forking with explicit lineage so household adaptations and recommendations can be
personalized without erasing the original. Record outcomes against immutable versions, not a mutable slug, so a
later edit cannot rewrite the history of what people actually cooked.

### Cross-Device and Offline Continuity

After moving shared operational state server-side, add an installable offline-capable web experience for
recipes, active timers, the current plan, and the current shopping trip. Tandoor demonstrates the value of both
[PWA installation with recently viewed recipes cached offline](https://docs.tandoor.dev/faq/) and
[shared shopping lists with automatic synchronization](https://docs.tandoor.dev/features/shopping/).
Recipe Site should go further by making offline edits converge safely when connectivity returns.

## Parallel Product Tracks

### Collection Migration and Review

Turn the existing single URL, Cooklang file, and photo flows into a durable batch-import workspace. Each source
should become an independently reviewable draft with provenance, duplicate detection, retry/skip states,
autosaved corrections, and **Save and next**. Collection archives need whole-batch recovery; photo batches need
an explicit thumbnail grouping and ordering step before extraction.

Tandoor's broad
[recipe-manager import support](https://docs.tandoor.dev/features/import_export/) makes migration breadth a
competitive baseline. Migration matters because a social graph without people's real family collections has a
cold-start problem, but accepting more file extensions is not itself the differentiated product.

### Library Organization and Data Hygiene

Add cookbooks or named collections, favorites and personal rankings, saved searches, and bulk organization.
Tandoor is particularly strong here: it combines cookbooks with customizable full-text search, batch tagging,
and tools to merge or rename foods, units, and tags. Recipe Site already has canonical ingredient and cookware
registries; the next step is exposing aliases, merges, and import cleanup rules as safe user-facing workflows.
Tandoor's [import automations](https://docs.tandoor.dev/features/automation/) are a useful reference, especially
for recurring source-specific cleanup.

### Household Coordination

Extend the shared pantry into quantities, freshness, prepared portions, and explicit uncertainty. Add household
activity and lightweight notes where they reduce coordination cost. Keep public follows and discovery separate
from trusted household collaboration: they are different permission, evidence, and notification models, even if
they sometimes share UI components.

### Cooking Depth

Add portion-size memory, hands-free step navigation, and eventually multi-recipe cooking with a shared timer
timeline. Continue testing cooking mode during real meals; interaction quality under time pressure matters more
than adding decorative recipe metadata.

### Passive Nutrition, Cost & Suggestions

Calculate nutrition per recipe and serving, then let completed cooking sessions populate an approximate food
history automatically. Ask for corrections only when reality differed materially: a different portion, skipped
ingredient, substitution, shared meal, or unrecorded food. Avoid streaks and completeness pressure; a partially
observed week should still improve the next decision without pretending to be a clinical record.

Use the highest-confidence source available: the exact cooked recipe and serving first, a known leftover or
frequent meal second, a packaged-product barcode for a genuine exception, and photo inference only as an
optional draft. Barcode scans should replace or amend a known ingredient rather than force people to construct
meals product by product. A meal photo is successful only if confirming or correcting it is materially faster
than entering the meal another way.

Tandoor's model of calculating
[nutrition, price, diet points, or other ingredient-derived properties](https://tandoor.dev/) suggests a useful
generalization: build an extensible property engine rather than hard-code calories as a one-off. Samsung Food
similarly normalizes recipe ingredients to grams and calculates macro- and micronutrients automatically
([methodology](https://support.samsungfood.com/hc/en-us/articles/18725068057620-Nutrition-calculations-Macronutrients-Micronutrients-and-Health-Score)).
Recipe Site should use that foundation at decision points—recipe comparison, meal planning, basket building, and
adaptation—not require a parallel diary whose main output is retrospective scoring. It can also support
seasonality, cost, waste, and "what can I make?" ranking using household context and social evidence.

### Portability and Operations

Broaden round-trip import/export, add collection-level backup and restore, and document the stable public API.
Where users connect external storage, prefer explicit read-only or one-way modes before attempting conflict-prone
two-way synchronization. Tandoor's many importers and Dropbox/Nextcloud integration show the demand; Recipe
Site should preserve provenance and reversibility as the differentiator.

## Longer-Horizon Bets

* **Social media ingestion** from Instagram, TikTok, YouTube, and Facebook once the batch review model can absorb
  noisier sources
* **Constraint-aware meal assistance** after server-backed planning, nutrition, kitchen state, and behavioural
  signals are trustworthy; use AI only where it improves the explanation or plan, not as the product thesis
* **Printed recipe books** as a gift or archival artifact that complements the digital collection
* **Seasonal and neglected-recipe suggestions** driven by ingredient seasonality and the existing cooking log

# Why Digital Beats Physical

| Dimension          | Physical Book                                | Recipe Site                                    |
| ------------------ | -------------------------------------------- | ---------------------------------------------- |
| **Access**         | Must be near the book                        | Any device, anywhere                           |
| **Search**         | Flick through every page                     | Instant full-text search                       |
| **Filter**         | Read every recipe's details                  | One-click by cuisine, time, ingredient         |
| **Edit**           | Destructive — rewrite entire page            | Edit in place; version history is next         |
| **Share**          | Physically hand over the book                | Send a link                                    |
| **Backup**         | Single copy, can be lost                     | Managed database + encrypted backups           |
| **Shopping**       | Manual transcription to phone                | Auto-generated checklist                       |
| **Portioning**     | Mental arithmetic, easy to forget mid-recipe | Click a button, page shows the truth           |
| **Units**          | Whatever the source used                     | Converted to your preference                   |
| **Adding recipes** | Must be with book, manual handwriting        | Paste, import, or photograph from anywhere     |
| **Kitchen UX**     | Easy to prop open, no lock screen            | Cooking mode: large text, step-by-step, timers |

# What This Preserves From the Physical Book

The physical book isn't all bad. The recipe site should preserve its strengths:

* **Glanceability** — cooking mode replicates the "propped open book" experience with large, readable text
* **No fiddling** — large tap targets, no tiny buttons, no accidental navigation
* **Resilience** — wake lock and persistent timers reduce interruptions today; offline recipes remain a critical-path gap
* **Tangibility** — a future printed-book export can create a physical artifact when the occasion calls for it

# Product Design

The product has been designed end-to-end as a mid-fidelity prototype — every
surface, in both desktop and mobile, rendered in a warm "paper and handwriting"
visual language (a soft paper palette with Caveat, Kalam, and JetBrains Mono
type) that deliberately evokes the physical recipe book this replaces.

It spans 17 surfaces: the recipe box and recipe read/cook views, scan/import,
the kitchen (pantry + freezer), shopping and meal planning, sharing, cookbooks,
a public profile, a profile-wide diet, a full shared-household system, recipe
lineage/provenance, a cook log, the logged-out home and discover feed,
onboarding, a recommendations inbox, notifications, and a settings hub. Much of
it is interactive — cooking-mode timers run live, and a "tweaks" panel re-casts
household size, diet model, and activity density across the artboards.

This began as a design exploration rather than a commitment to build every surface. It has since shaped the
live product: cooking mode, kitchen, shopping and meal planning, profiles, households, diet settings,
recommendations, notifications, onboarding, and the cook log all draw from it. Unbuilt surfaces remain prompts
for discovery, not a promise or delivery sequence.

The prototype already contains an important piece of the differentiated vision that the earlier written
strategy failed to explain: recommendation cards show behavioural signals such as **made 128×** and **54% made
it again**, distinguish household members from followed cooks, and connect a personal note directly to save,
plan, and cook actions. The roadmap now treats that as the core system to make real—not decorative social proof
around an otherwise conventional recipe manager.

*(Interactive DesignEmbed component — view it on the HTML page)*

The prototype above is a self-contained build; the editable design source
(tokens, shared components, and one file per screen) is vendored alongside this
document under [`designs/`](https://github.com/Robbie-Palmer/personal-site/tree/main/ui/content/projects/recipe-site/designs).

# Competitor Analysis

The recipe app market has moved beyond the fragmented feature landscape that motivated this project. No single
product leads every part of the lifecycle, but several now cover most of it. As the Cooklang team
[put it](https://cooklang.org/blog/09-cooklang-vs-paprika-vs-mealie/): "every step between 'I want to
make that' and 'I'm cooking' is a chance to order takeout instead." The most polished cooking experiences still
skew toward Apple's ecosystem. Import apps have expanded rapidly beyond capture. Self-hosted products cover the
whole management loop: Tandoor now
combines a PWA, offline caching, AI-assisted image/PDF/text import, meal planning, shared shopping, cookbooks,
and extensive migration tooling. Samsung Food connects communities, "Made It" actions and reviews, shared
planning and shopping, personalized plans, and a Food List that can update after cooking. The remaining
opportunity is not an empty feature checklist or the claim that nobody has connected food and social interaction.

Flavorish's rapid expansion from import into cooking, meal planning, shared shopping, and collection migration
shows that product breadth can converge quickly. Recipe Site therefore needs a model competitors would have to
reorganize around: a public graph of real cooking activity, exact recipe lineage, socially relevant evidence,
and household context. Cooking correctness, reviewable ingestion, owned data, and good household UX remain
important supporting advantages, but none is a sufficient vision alone.

General social media is also a discovery competitor even when it is not a recipe manager. TikTok explicitly
describes video completion as a strong interest signal and advises creators that watch time affects distribution
([recommendation system](https://newsroom.tiktok.com/how-tiktok-recommends-videos-for-you),
[creator guidance](https://newsroom.tiktok.com/5-tips-for-tiktok-creators?lang=en)). It also acknowledges filter
bubbles and deliberately injects diverse content. The structural mismatch is not that these systems make no
attempt at relevance or diversity; it is that they can observe whether food content was watched, liked, or
shared, but usually not whether the viewer cooked the recipe, enjoyed the result, changed it, or made it again.
Recipe Site can optimize for those downstream outcomes because it owns the rest of the food journey.

## The Build-or-Use Test

If the job is to manage a large recipe collection, plan meals, share shopping lists, and self-host the data,
**use Tandoor**. It is mature and far ahead of this project in collection administration and migration. If the
job is broad community discovery, nutrition, grocery integration, and personalized planning, **evaluate Samsung
Food**. Native cooking polish may make Crouton or Paprika the better choice for an Apple-centric household.

Continuing to build Recipe Site is strategically justified by a different thesis: a public network becomes more
useful whenever somebody actually cooks, repeats, recommends, or improves a recipe, while trust relationships
and kitchen context turn that collective evidence into a better next decision. Competitor features are the
commodity baseline. If this flywheel does not become useful in real friend and family networks, the honest
outcome is to migrate to Tandoor rather than maintain a less capable recipe manager.

## Market Landscape

| Segment                       | Examples                                           | Core focus                                         |
| ----------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| **Recipe managers**           | Paprika, Crouton, Mela, Copy Me That, AnyList      | Store, organise, and cook your own collection      |
| **Self-hosted / open-source** | Mealie, Tandoor, RecipeSage, Nextcloud Cookbook    | Data ownership, administration, developer audience |
| **AI-powered capture**        | Flavorish, Honeydew, Recify, Recipe One, Preplo    | Import from social media, photos, and URLs with AI |
| **Social cooking networks**   | Samsung Food, SideChef, Allrecipes                 | Communities, reviews, discovery, and sharing       |
| **Meal planning / diet**      | Ollie, ZOE, Mealime, Samsung Food                  | Weekly plans, grocery delivery, and nutrition      |
| **Editorial platforms**       | NYT Cooking, BBC Good Food, Allrecipes, Epicurious | Curated content and community commentary           |

Recipe Site crosses personal management, owned infrastructure, AI-assisted capture, planning, and social
cooking. That breadth is not itself the advantage. The connective tissue is: exact versions of structured
recipes, a public graph of observed use, relationship-aware ranking, and a household operating model.

## Key Competitors

**[Paprika Recipe Manager 3](https://www.paprikaapp.com/)** — The incumbent. iOS, Android, Mac, and Windows
versions are purchased separately. The mature feature set includes a built-in browser, auto-detected timers,
interactive cooking, ingredient scaling and conversion, pantry-aware grocery lists, reusable meal plans,
offline access, and cloud sync. But there is no web version, the UI feels dated, and separately purchasing each
platform adds friction.

**[Crouton](https://crouton.app/)** — Best-in-class cooking UX and the
[2024 Apple Design Award winner for Interaction](https://developer.apple.com/design/awards/2024/). One step at a
time with large font, wink-to-advance navigation, and multiple tappable timers. It has grown into automated
meal planning, shopping lists, OCR scanning, metric/imperial conversion, and iCloud household sharing. The
constraint is ecosystem reach: it remains Apple-only, with no web or Android client.

**[Mealie](https://mealie.io/)** — Self-hosted, open source (Vue + Python), REST API, schema.org Recipe
format, ML-powered ingredient parsing. Multi-user with granular permissions and comment threads — the
Cooklang blog [describes](https://cooklang.org/blog/09-cooklang-vs-paprika-vs-mealie/) a family in Italy
using Mealie to preserve a 100-year-old recipe collection across three generations who contribute, comment,
and adapt recipes. This multi-generational collaboration model is directly relevant to our recipe forking
and personalisation roadmap. Mealie is now a PWA with meal plans, shopping lists, groups, and households, but
its emphasis remains recipe management and collaboration rather than a dedicated, timer-rich cooking flow.
([GitHub](https://github.com/mealie-recipes/mealie))

**[Tandoor Recipes](https://tandoor.dev/)** — The strongest self-hosted comparison by feature breadth and
the clearest challenge to the original competitive thesis. Its 8,500-star repository combines meal planning,
shopping lists, cookbooks, family collaboration, customizable full-text search, batch tagging, canonical data
cleanup, recipe scaling, URL import, and Dropbox/Nextcloud sync
([GitHub](https://github.com/TandoorRecipes/recipes)). It is also an installable
[PWA that caches recently accessed recipes for offline use](https://docs.tandoor.dev/faq/), and its shopping
lists support supermarket-specific ordering, sharing, and automatic synchronization between users
([docs](https://docs.tandoor.dev/features/shopping/)).

Tandoor is ahead on operating a large, long-lived collection. It imports archives from many established recipe
managers and supports round-trip formats including its native representation and RecipeSage
([import/export matrix](https://docs.tandoor.dev/features/import_export/)). Its current AI layer imports images,
PDFs, and text, links ingredients to steps, and derives nutrition or other properties through configurable
LiteLLM providers with usage and cost controls ([AI docs](https://docs.tandoor.dev/features/ai/)). The trade-offs
are a power-user product with self-hosting overhead and a permission system its own documentation still describes
as unsuitable for completely untrusted users ([permission docs](https://docs.tandoor.dev/system/permissions/)).
There is no similarly differentiated, step-by-step cooking mode in its documented core feature set. The lesson
for Recipe Site is to keep its stronger cooking interaction while learning from Tandoor's migration breadth,
library hygiene, offline support, and household shopping coordination.

**[Samsung Food](https://samsungfood.com/)** — The strongest challenge to the social-kitchen vision, not merely
an adjacent meal-planning app. It has public and private communities, conversations, recipe sharing,
collaborative meal plans and shopping lists, personalized plans, and a cross-platform web/mobile product. Its
["Made It" and review model](https://support.samsungfood.com/hc/en-us/articles/18588391246740-Recipes-Made-Its-and-Review-FAQs)
records that somebody cooked a recipe and exposes ratings, notes, and photos. Its Food List tracks ingredients
by storage location and use-by date; after a user marks a recipe made, it can
[suggest removing ingredients that were used](https://support.samsungfood.com/hc/en-us/articles/30025317487508-Getting-Started-with-Food-List).

The core product is device-agnostic: Samsung documents clients for
[web, iOS, Android, and a Chrome extension](https://support.samsungfood.com/hc/en-us/categories/360003109252-Samsung-Food-Apps),
and even directs people in unsupported app regions to the web client. Samsung hardware is not required. The
experience is not identical everywhere, however: some features are mobile-only or subscription-gated, a Samsung
Account is recommended for reliable cross-device data synchronization, and SmartThings appliance control is
necessarily ecosystem-specific.

It also reaches beyond list-making. Samsung Food's grocery layer maps recipe ingredients to real products and
[sends baskets to integrated retailers](https://support.samsungfood.com/hc/en-us/articles/360042706091-Integrated-Stores),
including Tesco, Ocado, Amazon Fresh, and Sainsbury's in the UK and Walmart, Instacart, and Amazon Fresh in the
US. Its nutrition engine automatically derives macro- and micronutrients from normalized recipe ingredients.
That makes it a full-lifecycle competitor as well as a social one.

Samsung Food proves that neither social recipes, public cooking signals, nor a basic kitchen twin is unique.
The opening is in how those models connect. Its communities organize broad interests, while Recipe Site can
combine global evidence with the cooks a person follows and the constraints of the kitchen they are standing
in. Samsung's documentation says editing a saved recipe creates a "tweak" and removes the original ratings and
reviews because they may no longer apply. Recipe Site should model that distinction explicitly: preserve
lineage, attach outcomes to the exact cooked version, and roll evidence up carefully across related versions.

Samsung's Home Feed already includes recipes personalized to stated preferences and asks whether users would
make recent recipes again
([feed documentation](https://support.samsungfood.com/hc/en-us/articles/18758565761812-About-Your-Home-Feed)).
Its first-party documentation does not establish taste-neighbour matching based on shared cook and repeat
behaviour, so that should be treated as a proposed distinction rather than a claimed gap verified through
hands-on product testing.

**[RecipeSage](https://recipesage.com/)** — Open source, web-based, with meal planning, shopping lists,
and fuzzy search with synonym mapping. Notable for being one of the few apps that
[scales instruction text quantities](https://docs.recipesage.com/docs/tutorials/recipes/edit-recipe/)
using curly-brace markup — though it requires manual annotation.

**[Recify](https://www.recify.app/)** — AI import from YouTube, Instagram, TikTok, Pinterest, and blogs.
Its current first-party site confirms customizable collections, full-screen swipe-based cooking mode, editing,
and recipe sharing on iOS and Android. It does not clearly document timer or voice support, storage architecture,
multi-device synchronization, current import limits, or pricing, so those should not be treated as established
competitive facts without testing the app.

**[Flavorish](https://www.flavorish.ai/)** — The most credible commercial full-stack competitor. It imports from
Instagram, TikTok, YouTube, Facebook, websites, and photos of handwritten recipes. It now has collections,
weekly meal planning, multi-recipe cooking mode,
aisle-sorted grocery lists with real-time sharing, cloud sync across iOS/Android/web, and
[bulk migration from five established recipe apps](https://www.flavorish.ai/blog/importing-from-other-recipe-apps).
The free tier keeps unlimited website imports and core planning; Premium is $4.99/month for unlimited AI/social/
image imports. "No ads. No data-selling." Its product breadth means Recipe Site must differentiate on data
ownership, cooking correctness, and transparent review—not simply on having a cooking screen.

**[Honeydew](https://honeydewcook.com/)** — AI extraction from social media, websites, and photos; AI meal
planning; Instacart integration; metric/imperial support; screen-on cooking; and offline recipes and shopping.
Its support documentation confirms real-time multi-device synchronization, but describes family use as sharing
one account and credentials rather than a granular household permission model. The free tier is limited and Plus
pricing varies by platform and region. Honeydew's marketing blog claims voice cooking and automatic timers, but
those features are not corroborated by its current support overview or Google Play listing, so they are excluded
from the comparison. "Pantry Mode" lets people photograph their pantry for suggestions—an interesting concept
whose recognition reliability still needs real-world validation.

**[Copy Me That](https://www.copymethat.com/)** — A mature web and mobile personal recipe manager with a web
clipper, meal planner, and aisle-sorted shopping lists. Current first-party pages do not make its cooking-mode,
timer, recipe-limit, or pricing position clear enough to use those as comparison facts without testing the app.

**[Cooklang](https://cooklang.org/)** — The closest philosophical match and a potential architectural
building block. We share many of the same pain points and motivations — their
[comparison post](https://cooklang.org/blog/09-cooklang-vs-paprika-vs-mealie/) articulates the same
friction we identified with physical recipe books, and their conclusion — "the best recipe manager isn't
the one with the most features, it's the one that removes barriers between you and cooking" — aligns
directly with our building philosophy. Recipes are plain-text `.cook` files stored in git, with inline
annotations for
ingredients (`@flour{200%g}`), cookware (`#pot{}`), and timers (`~{25%minutes}`). The core
[`cooklang-rs`](https://github.com/cooklang/cooklang-rs) Rust crate (MIT licensed, actively maintained)
provides a clean parse → scale → convert pipeline with WASM/TypeScript bindings, meaning it can run
in-browser. The [CLI](https://github.com/cooklang/cookcli) (Rust/Axum) includes a local web server,
shopping list generation with ingredient aggregation across recipes, pantry management (find recipes
makeable from what you have), AI-powered import from URLs using multiple providers (OpenAI, Claude, Gemini,
Ollama), and full-text search. The ecosystem includes parsers in 12+ languages, editor support (VS Code,
[Obsidian plugin](https://github.com/cooklang/cooklang-obsidian) with 308 stars, LSP), and a community
recipe index.

Because ingredients are inline-annotated in the markup, the parser inherently knows which quantities in
instructions to scale. It also supports fixed quantities (`@salt{=1%tsp}` — the `=` prefix prevents
scaling for things like baking powder that shouldn't change with servings), recipe references
(`@./Shakshuka sauce{100%g}` — sub-recipes as composable ingredients), and named timers
(`~eggs{3%minutes}`).

The ecosystem is broader than just the CLI — there are native iOS and Android apps with iCloud/CookCloud
sync, offline support, shopping lists grouped by store section, and recently-added timer support. But the
UX maturity is limited: the iOS app has a
[3.8/5 rating](https://apps.apple.com/us/app/cook-cooklang-recipe-app/id1598799259) with only 4 reviews
and reports of bugs (accidental recipe deletion, crashes). Their own
[blog](https://cooklang.org/blog/09-cooklang-vs-paprika-vs-mealie/) positions it honestly — Cooklang
removes friction "through simplicity" while Paprika does it "through polish" — and the audience is
primarily developers and data scientists. There's no dedicated cooking mode optimised for kitchen use
(large text, step-by-step, wake lock). The data model and parsing infrastructure are strong — worth
evaluating as a foundation to build a polished kitchen experience on top of, rather than reimplementing
from scratch.

**[ZOE](https://zoe.com/en-us/app)** — An important product lesson rather than a direct recipe-manager
competitor. Its current app has reduced manual entry through meal photos and barcode scans, then scores food,
tracks habits and streaks, and connects logs to personalized nutrition coaching. ZOE's own evaluation concedes
that visually ambiguous foods such as soup are difficult to identify and that quantities remain difficult to
estimate ([photo-logging evaluation](https://zoe.com/learn/zoe-new-photologging-app)).

In my own use, barcode scanning still worked at ingredient or packaged-product level, leaving me to reconstruct
the meal from its parts. Complete-meal photos were practically useless without extensive human editing to make
them accurate. The food log therefore remained too costly to maintain, while the gut-health tests and scores did
not change enough day-to-day decisions to sustain the habit.

Recipe Site should invert that model: planning, shopping, and cooking are already necessary actions, and a
structured recipe plus selected serving is already a much stronger description of a meal than a photograph. The
system should derive nutrition from those actions, return it at the next useful decision, and ask the user to
correct exceptions instead of recreating every meal in a parallel diary.

## Batch Import and Review Patterns

Recipe products divide import into two distinct experiences. Adding one uncertain recipe normally
opens an editor for confirmation, while moving a whole collection normally creates a durable
background job with progress, per-item errors, and a way to identify or undo the resulting records.
The useful opportunity is to combine those patterns: durable batch processing followed by a
focused, item-by-item review queue.

| Product or pattern                                                                                                                   | Batch behaviour                                                                                                                                                                                                                                                                                                                                                  | Review and recovery behaviour                                                                                                                                                                      | Lesson for Recipe Site                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **[RecipeSage](https://docs.recipesage.com/docs/tutorials/settings/import/)**                                                        | Accepts newline-separated [URL lists](https://docs.recipesage.com/docs/tutorials/settings/import/urls/) and ZIP archives containing one recipe per [text file](https://docs.recipesage.com/docs/tutorials/settings/import/textfiles/), PDF, or [image](https://docs.recipesage.com/docs/tutorials/settings/import/images/). Imports continue as background jobs. | Every import receives an automatic label, making the batch easy to find and delete. It warns against retrying jobs because duplicates can be created.                                              | Make recipe boundaries explicit, persist the import as a first-class object, and provide batch-level recovery.                               |
| **[Plan to Eat](https://learn.plantoeat.com/help/import-recipe-files-from-other-programs)**                                          | Imports established collection formats, supports up to 3,000 recipes in one file, and continues after the user leaves the page.                                                                                                                                                                                                                                  | Users choose whether matching titles should be overwritten. Progress and failures are reported beside individual recipe titles.                                                                    | Decide duplicate policy during preflight and isolate failures to individual items rather than failing the batch.                             |
| **[Paprika](https://www.paprikaapp.com/help/windows/)** and **[AnyList](https://www.anylist.com/recipes/browser-extensions/safari)** | Paprika imports trusted database formats wholesale; both products handle ordinary website capture one recipe at a time.                                                                                                                                                                                                                                          | Individual web imports are shown in an editable recipe screen before the user saves them.                                                                                                          | Keep migration and everyday capture as related but distinct modes, and reuse the familiar edit-before-save experience for uncertain results. |
| **[CookBook](https://help.cookbookmanager.com/en/article/how-to-import-recipes-from-another-app-1wqhgjs/)**                          | Individual files are self-service, while large collection transfers are queued as a separate assisted service.                                                                                                                                                                                                                                                   | A single imported file is reviewed before saving; collection imports complete in the background and notify the user.                                                                               | A collection import is migration infrastructure, not merely a file input with `multiple` enabled.                                            |
| **Document and receipt tools**                                                                                                       | [Expensify](https://help.expensify.com/articles/expensify-classic/expenses/Add-an-expense) treats rapid-fire receipt photos as separate items. [Dext](https://help.dext.com/en/articles/416680-why-was-my-document-rejected) sends uploads containing several transactions to a manual split tool.                                                               | [Adobe Acrobat](https://helpx.adobe.com/acrobat/web/edit-pdfs/organize-documents/organize-pages.html) uses a visual thumbnail workspace to reorder, insert, rotate, or remove pages before saving. | For photos, expose page grouping and ordering before extraction instead of relying on an invisible boundary guess.                           |

### Product Direction

The batch experience should be one persistent workspace rather than many browser tabs or unrelated
editor pages. Each draft still gets a stable route for refresh and back-button safety, but the
interface keeps the queue, selected editor, and live preview together. Edits autosave to the import
draft; **Save recipe** promotes only that item into the recipe box; **Save and next** advances to
the next item needing review.

Delivery is deliberately phased:

1. **URL lists and local recipe files.** One URL or file equals one recipe. Add preflight
   validation, duplicate warnings, durable background processing, and the review queue.
2. **Collection archives.** Expand supported archive formats into the same review queue, retain
   source provenance on every accepted recipe, and support whole-batch undo.
3. **Photo batches.** Add a thumbnail grouping board where users can create, split, merge, and
   reorder recipe groups before extraction.

## Feature Comparison

The comparison is split because management-first and import-first products create different competitive
pressures. A single very wide matrix obscured more than it revealed.

This is a first-party-documentation comparison, not an exhaustive hands-on review. "Not documented" means the
current product site or docs do not establish the capability; it is deliberately not converted into "No."

### Daily Use and Collection Management

| Capability                       | Paprika                  | Crouton               | Mealie                      | Tandoor                                 | **Recipe Site**                              |
| -------------------------------- | ------------------------ | --------------------- | --------------------------- | --------------------------------------- | -------------------------------------------- |
| **Cross-platform web**           | No                       | Apple only            | Self-hosted PWA             | **Hosted or self-hosted PWA**           | **Public web app**                           |
| **Dedicated cooking mode**       | Interactive view         | Excellent             | Not documented as dedicated | Not documented as dedicated             | **Yes, step-by-step**                        |
| **Persistent / inline timers**   | Auto-detected            | Tap-to-start          | Not documented              | Not in documented core features         | **Yes, multiple + custom**                   |
| **Scaling and conversion**       | Metric/imperial          | Metric/imperial       | Ingredient scaling          | Scaling, fractions, decimals            | **List + instruction scaling; metric/US/UK** |
| **Offline use**                  | Native                   | Native                | Not documented              | **Recent recipes cached in PWA**        | Not yet                                      |
| **Meal planning**                | Yes                      | Yes + auto-generate   | Yes                         | **Multiple meals per day**              | **Yes; currently device-local**              |
| **Shopping**                     | Synced lists             | Yes                   | Yes                         | **Shared, auto-sync, store order**      | **Merged, aisle-sorted, device-local**       |
| **Pantry / cook-from-stock**     | Pantry list              | Not documented        | Not documented              | **Ingredient-based recipe search**      | **Pantry + household stock matching**        |
| **Collection administration**    | Mature categories        | Lightweight           | Tags and groups             | **Cookbooks, batch tags, merge/rename** | Filters and canonical registries             |
| **Multi-user collaboration**     | Shared cloud account     | **iCloud households** | Users, groups, households   | **Spaces, roles, links**                | **Households, follows, recommendations**     |
| **Portable structured data**     | `.paprikarecipes` export | Not documented        | API / schema.org            | **Broad import/export matrix**          | **Cooklang, Markdown, schema.org JSON**      |
| **User-visible version history** | Not documented           | Not documented        | Not documented              | Not documented                          | Roadmap                                      |

### Capture and Migration

| Capability                  | Flavorish            | Recify            | Honeydew                    | Tandoor                             | **Recipe Site**                       |
| --------------------------- | -------------------- | ----------------- | --------------------------- | ----------------------------------- | ------------------------------------- |
| **Website import**          | AI                   | AI                | AI                          | Structured web import               | **schema.org import**                 |
| **Photo / document import** | AI photos            | AI photos         | AI photos                   | **AI image, PDF, and text**         | **AI photo workflow**                 |
| **Social media import**     | Major platforms      | Major platforms   | Major platforms             | No documented first-class flow      | Roadmap                               |
| **Collection migration**    | Several app archives | Not documented    | Not documented              | **Many app archives and formats**   | Cooklang files today; batch roadmap   |
| **Correction workflow**     | Edit after import    | Editing confirmed | **Review/edit before save** | Import/editor flow                  | **Live editor; durable queue next**   |
| **AI provider choice**      | Vendor-managed       | Vendor-managed    | Vendor-managed              | **LiteLLM providers + cost limits** | OpenRouter behind owned pipeline      |
| **Storage ownership**       | Vendor cloud         | Not documented    | Vendor cloud                | **Self-host or hosted**             | **Owned database + portable exports** |
| **Cooking after capture**   | Multi-recipe mode    | Full-screen swipe | Screen-on + offline         | Standard recipe view                | **Step mode + persistent timers**     |

### Personal Food Lifecycle

| Capability                         | Tandoor                          | Samsung Food                           | ZOE                               | **Recipe Site**                             |
| ---------------------------------- | -------------------------------- | -------------------------------------- | --------------------------------- | ------------------------------------------- |
| **Device reach**                   | Web/PWA                          | **Web, iOS, and Android**              | iOS and Android                   | **Any modern web browser**                  |
| **Capture and recipe management**  | **Broad and mature**             | Website, builder, photo                | Meal photos and barcode scans     | URL, Cooklang, photo; batch next            |
| **Meal planning**                  | **Shared, server-backed**        | **Shared + personalized**              | Not a documented core flow        | Device-local today                          |
| **Shopping list**                  | **Shared, synchronized**         | **Shared, recipe/product-aware**       | Shopping guidance                 | Merged and aisle-sorted; device-local       |
| **Retailer basket hand-off**       | Not documented as a core feature | **Integrated regional retailers**      | Not documented                    | Roadmap after server-backed shopping        |
| **Kitchen stock**                  | Ingredient-based recipe search   | **Food List + post-cook suggestions**  | Not documented                    | **Shared pantry and stock matching**        |
| **Guided cooking**                 | Standard recipe view             | Guided/AI cooking on supported clients | Not a documented core flow        | **Step mode, timers, and wake lock**        |
| **Nutrition from recipes**         | Nutrition/properties             | **Automatic macro/micronutrients**     | Nutrition inferred from meal logs | Roadmap from structured ingredients         |
| **Low-effort consumption history** | Not clearly documented           | "Made It" plus optional review         | Requires repeated photo logging   | **Cook starts/completions; inference next** |
| **Leftovers and repeat loop**      | Not documented                   | Not documented as a connected loop     | Not documented                    | Roadmap: portions → leftovers → repeat      |

This table explains why personal utility is not separable from the social strategy. Samsung Food covers more of
the lifecycle than the earlier analysis acknowledged, while Tandoor is a stronger everyday operating tool than
many social products. Recipe Site needs both qualities: the personal loop must be worth using alone, and its
normal use must generate the evidence that powers the public graph.

### Social Learning and Kitchen Context

| Capability                             | Tandoor                                      | Samsung Food                               | **Recipe Site**                                        |
| -------------------------------------- | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------ |
| **Public discovery network**           | Not intended as a public site                | **Public profiles and communities**        | **Public profiles, recipes, follows, and feeds**       |
| **Direct trusted recommendations**     | Recipe sharing and spaces                    | Sharing and community contribution         | **Person-to-person recommendations with attribution**  |
| **Taste-neighbour discovery**          | Not documented                               | Preference personalization; method unclear | Roadmap: affinity from cooks, repeats, and adaptations |
| **Taste versus practical fit**         | Not documented as distinct                   | Not documented as distinct                 | Roadmap: separate enjoyment, utility, and context      |
| **Behaviour-seeded communities**       | Spaces are administrator-defined             | User-created interest communities          | Roadmap: suggested by affinity, governed by people     |
| **Observed cooking signal**            | Ratings; cook history not clearly documented | **"Made It," ratings, notes, and photos**  | **Started/completed cooking sessions**                 |
| **Repeat-cook evidence**               | Not documented as a distinct signal          | Not documented as a distinct signal        | Roadmap: distinct public and relationship signals      |
| **Adaptation lineage**                 | Not documented                               | Tweaks become detached copies              | Roadmap: explicit version and fork graph               |
| **Household kitchen context**          | Shared planning and shopping                 | Food List, shared plans, shopping          | **Diet, pantry, cooking log; shared plan next**        |
| **Recommendation-to-outcome loop**     | Not documented                               | Features exist; linkage not documented     | Roadmap: recommendation → repeat attribution           |
| **Explainable relationship weighting** | Not documented                               | Personalized feed; method not documented   | Roadmap: global, followed-cook, and household evidence |
| **Deliberate exploration**             | Not documented                               | Not documented                             | Roadmap: tune familiarity versus adjacent novelty      |

This is the comparison that matters to the revised vision. Tandoor remains the operational benchmark and
Samsung Food already has substantially more of the social and kitchen loop than the original analysis
recognized. Recipe Site's proposed distinction is not the presence of any one row; it is treating the entire
sequence as one version-aware, explainable graph whose public outcomes improve discovery.

## Where We Differentiate

**Come for the food tool; stay for the network.** The product must earn repeated personal use across capture,
planning, shopping, cooking, leftovers, and nutrition before its social graph has meaningful data. Unlike a
social feed with utility bolted on, each personal action should make the next action easier and create an honest
signal as a by-product. Tandoor is the benchmark for this operating depth; Samsung Food is the benchmark for how
much of the lifecycle and network a cross-platform commercial product can connect.

**Taste neighbours, not just influencers.** Explicit follows preserve recommendations from people already
trusted; behavioural affinity discovers useful strangers. Someone who repeatedly cooks the same dishes as you
is evidence about taste even if they have no audience, publishing cadence, or creator brand. When that person
successfully crosses into a new cuisine or technique, their outcome can become a credible bridge out of your
food bubble. Communities can then form around demonstrated affinity and exploration, not only celebrity reach
or broad declared categories.

**Value generated, not one rating.** Deliciousness and practical fit are different outputs. A five-star recipe
that earns its place once a year and a dependable meal that quietly solves every Tuesday should both be visible
for what they do. Planning, shopping, cooking, repeat, leftover, and adaptation behaviour can reveal effort,
reliability, and routine fit that a review cannot, while lightweight feedback supplies the meaning behaviour
alone lacks. Frequency is evidence, not the new universal score.

**A public graph of what people actually cook.** Public recipes, follows, and discovery are already live. The
next step is to make completed cooks, repeats, attributed adaptations, and recommendation outcomes first-class
public signals. This creates the network effect: every real outcome can improve recipe ranking, reward useful
contributors, reveal reliable cooks, and help the next person choose. Reviews and photos remain valuable
qualitative context, but they should not carry the same evidential weight as repeated behaviour.

**Exact lineage plus contextual ranking.** A signal is only trustworthy if it refers to the recipe version that
was cooked. Forks and immutable versions allow an adaptation to earn its own evidence without discarding its
relationship to the source. Global outcomes supply breadth, followed cooks and friends supply social relevance,
and the household twin supplies constraints such as diet, equipment, stock, time, and prior success. The ranking
can then explain itself instead of presenting a generic popularity score.

**Nutrition without a second job.** Structured recipe ingredients, selected servings, shopping activity, and
completed cooking sessions already describe much of a person's food. Use that operational trail to calculate
approximate nutrition and improve the next plan, basket, or adaptation. Do not make retention depend on users
photographing or reconstructing every meal solely to keep a diary complete.

**A cooking experience on the open web.** The premium cooking UX
([Pestle](https://9to5mac.com/2022/01/21/pestle-cooking-app-for-ios-release/), Crouton, Mela) is
mostly native. Recipe Site already provides a large-text step flow, wake lock, concurrent persistent timers,
and URL-shareable recipes without app-store distribution. Tandoor proves that installation and limited offline
use are no longer unique to this vision; completing the offline critical path is necessary to turn a strong web
cooking mode into a complete PWA proposition.

**Correctness from structured cooking data.** Cooklang-backed recipes allow quantities in instructions to update
alongside the ingredient list, not just the ingredient list alone (a
[documented limitation](https://help.anylist.com/articles/scale-recipe/) in virtually every competitor
including [AnyList](https://www.anylist.com/)). Fixed quantities can remain unchanged, cookware is filterable,
and the same source produces human-readable recipes plus portable Cooklang, Markdown, and schema.org views.

**Reviewable, measurable recipe ingestion.** The photo pipeline is no longer just a model experiment: the web
capture flow starts a durable workflow whose stage artifacts and model attempts are recorded. The DVC-managed
pipeline still provides the ground-truth dataset and evaluation loop used to improve extraction. The next
differentiator is the batch review workspace—provenance, explicit boundaries, duplicate decisions, and isolated
recovery—rather than pretending uncertain AI output is ready to publish. Handwritten recipe OCR remains an
[unsolved problem industry-wide](https://flavor365.com/how-to-scan-recipes-the-definitive-2026-guide/) —
no app reliably handles older cursive handwriting — making this a genuine technical differentiator if we
can solve it well.

**Open access and owned data.** Browsing public recipes requires no account or subscription. Signed-in users get
household and personal scopes without losing public link sharing. Recipes have portable structured
representations, while the application database and infrastructure remain under project control. User-visible
version history is still roadmap work; it should not be claimed as shipped merely because the earlier static
content happened to live in git.

**Iteration velocity.** Type-safe domain schemas, committed database migrations, isolated preview databases,
API governance, and end-to-end observability make rapid parallel delivery safer. This is still an enabler rather
than a user feature, but it explains how the product moved across cooking, ingestion, household, kitchen, and
social tracks without waiting for artificial phase boundaries.

**The physical book replacement angle.** No competitor explicitly positions as "your handwritten recipe
book, but better in every way." The Cooklang blog
[captures this instinct](https://cooklang.org/blog/09-cooklang-vs-paprika-vs-mealie/) through a user who
photographed her grandmother's recipe cards "just to have a backup" — then found the digital version
became the primary. The emotional story of replacing a treasured physical book — preserving glanceability,
resilience, and tangibility while eliminating the limitations — is under-exploited in the market.

## Where Competitors Are Ahead

| Capability                          | Market leader                                                                                                                                                                        | Recipe Site direction                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| **Offline and installability**      | [Tandoor](https://docs.tandoor.dev/faq/) and native apps                                                                                                                             | Critical path: offline recipes, active timers, plans, and shopping with safe resynchronization |
| **Collection migration breadth**    | [Tandoor](https://docs.tandoor.dev/features/import_export/)                                                                                                                          | Parallel track: batch queue and recovery first, then additional trusted formats                |
| **Library administration**          | [Tandoor](https://github.com/TandoorRecipes/recipes)                                                                                                                                 | Parallel track: collections, saved searches, bulk organization, aliases, and merge workflows   |
| **Shared shopping synchronization** | [Tandoor](https://docs.tandoor.dev/features/shopping/)                                                                                                                               | Move the device-local planner and list into household state                                    |
| **Retailer basket integration**     | [Samsung Food](https://support.samsungfood.com/hc/en-us/articles/360042706091-Integrated-Stores)                                                                                     | Validate one intermediary or retailer after server-backed shopping                             |
| **Automatic recipe nutrition**      | [Samsung Food](https://support.samsungfood.com/hc/en-us/articles/18725068057620-Nutrition-calculations-Macronutrients-Micronutrients-and-Health-Score)                               | Derive serving nutrition and passive history from structured recipes and completed cooks       |
| **Public social network**           | [Samsung Food](https://support.samsungfood.com/hc/en-us/articles/18365296571412-Getting-Started-with-Samsung-Food-Communities)                                                       | Turn follows and feeds into a cooking-outcome flywheel                                         |
| **Cooking feedback at scale**       | [Samsung Food](https://support.samsungfood.com/hc/en-us/articles/18588391246740-Recipes-Made-Its-and-Review-FAQs)                                                                    | Publish defined cook, repeat, adaptation, and recommendation-outcome signals                   |
| **Personalized discovery at scale** | [TikTok](https://newsroom.tiktok.com/how-tiktok-recommends-videos-for-you) and [Samsung Food](https://support.samsungfood.com/hc/en-us/articles/18758565761812-About-Your-Home-Feed) | Learn affinity from cooking outcomes and reserve space for explainable exploration             |
| **Voice / hands-free cooking**      | [Pestle](https://9to5mac.com/2022/01/21/pestle-cooking-app-for-ios-release/) (voice + wink), SideChef (voice + narrator)                                                             | Cooking-depth track now that cooking mode and timers are live                                  |
| **Recipe reviews**                  | [NYT Cooking](https://cooking.nytimes.com/) (community notes), [Mealie](https://mealie.io/) (multi-user comments + adaptations)                                                      | Follow recipe lineage and forking; avoid attaching all feedback to a mutable canonical recipe  |

### Out of scope

**One-off adapters for every supermarket** — retailer basket hand-off is now part of the intended lifecycle,
but maintaining a bespoke integration for every chain would overwhelm the core product. Start with a stable
intermediary or one relevant retailer, validate that people complete baskets, then expand according to measured
demand and partner quality.

**Smart appliance integration** ([Samsung Food](https://samsungfood.com/), SideChef/Home Connect) — same
maintenance concerns, fragmented smart home ecosystem. A feature that sounds impressive on a feature list
but rarely works well in practice.

**Pantry photo scanning** ([Honeydew](https://honeydewcook.com/)'s "Pantry Mode") — the "What Can I Make?"
concept is genuinely interesting, but photo-based pantry recognition is technically unreliable. We'd rather
use the manual pantry and recipe matching that have already shipped than invest in computer vision we can't
trust.

### Future consideration

**AI-generated meal plans** ([Ollie](https://ollie.ai/), Honeydew, Samsung Food) — worth evaluating only after
the product can rank and explain plans from server-backed household state, nutrition, pantry stock, cooking
history, social evidence, and preferences. AI may improve the interaction, but the differentiated asset is the
underlying cooking graph.

# Architecture

## Current: Static Frontend, Dynamic Product

The recipe site keeps a statically exported Next.js frontend on Cloudflare Pages, but it is no longer a static
content site:

* **Cloudflare Pages and Pages Functions** serve the web application, proxy same-origin APIs, and expose public
  Markdown, Cooklang, and schema.org Recipe representations
* **The recipe API Worker** owns recipes, authorization, profiles, households, pantry stock, diet settings,
  notifications, recommendations, follows, discovery, and cooking sessions
* **Neon Postgres through Hyperdrive** is the source of truth for accounts, recipes, collaboration state, and
  ingestion metadata; Drizzle owns committed, reviewed migrations
* **Better Auth** provides Google and GitHub login, account linking, session management, and administrative
  controls
* **The recipe-ingest Worker** runs durable Cloudflare Workflows, stores immutable stage artifacts in R2, and
  calls OpenRouter through the shared recipe-parsing package
* **TanStack Query** coordinates client/server state while Zod schemas and the shared recipe-domain package keep
  data boundaries explicit

The static shell still keeps delivery simple and public pages fast. Dynamic infrastructure was introduced only
where ownership, identity, long-running work, or shared state required it.

Some state remains deliberately local: active timers, unit preferences, meal plans, and shopping lists persist
in the browser. That was an effective first pass, but cross-device and household continuity now make the planner
and shopping store the most important boundary to move server-side.

## Social Cooking Graph

The current relational model already contains public recipes, follows, recommendation events, household state,
pantry items, and cooking sessions with separate start and completion timestamps. The next architectural step is
to connect them without reducing everything to analytics events. Product facts such as a completed cook, repeat,
fork, recommendation outcome, retailer hand-off, or leftover portion need durable domain records tied to the
exact recipe version, servings, actor, household where relevant, and chosen audience.

Public counts and rankings should be reproducible projections of those records, not mutable counters or opaque
model outputs. That makes definitions inspectable, allows ranking to evolve, and supports multiple views of the
same graph: global evidence for discovery, followed-cook evidence for social relevance, and household evidence
for immediate feasibility. Nutrition and cost should be similarly reproducible projections from versioned
ingredients and recorded portions, with corrections layered on top rather than copied into a separate diary.

Taste affinity and practical fit should be separate derived, versioned projections rather than one permanent
label on a person or recipe. Their inputs and purposes must remain distinguishable: declared dietary and
accessibility constraints filter unsuitable candidates; explicit follows express trust; enjoyment feedback and
shared favourites estimate taste; observed planning and cooking outcomes estimate contextual utility; the
exploration policy introduces novelty. Context can be declared for an occasion or inferred narrowly for recipe
fit, but the system must not infer that somebody is an athlete, has a mobility issue, is a parent, or holds any
other identity from their cooking pattern. Keeping these roles separate makes recommendations explainable and
allows the projections to be recalculated as circumstances change.

## Recipe Ingestion

URL imports extract schema.org data synchronously. Cooklang text and local files are parsed into the shared domain
model. Photo imports create persistent jobs and run extract → normalize → canonicalize → finalize as a durable
workflow; Postgres records job state and attempts while R2 retains source and stage artifacts. All three paths
lead to an editable preview before a recipe is saved.

Batch migration is the next architectural step. One URL or ordinary file should map to one review item;
collection archives should expand into independently recoverable items with shared provenance. Photo batches
need an explicit grouping board because one recipe may span several images. Failures and ambiguity must remain
item-scoped so one bad source never blocks the rest of a collection.

# Building Philosophy

This project follows my [building philosophy](/projects?tab=philosophy).

The recipe site is a textbook case for several principles:

* **Short feedback loops** — the static recipe list shipped first; real use then pulled cooking mode, timers,
  shopping, and kitchen state forward
* **Validate pain, not feature presence** — an import, scan, recommendation, or nutrition screen is not successful
  because it shipped; it succeeds only when it removes more work than it creates during real use
* **Build flywheels** — every published recipe or adaptation expands the graph; every completed and repeated cook
  adds evidence; better evidence improves discovery and recommendations; better discovery drives more cooking
* **Leverage tech debt** — version-controlled recipe content was the right starting constraint; recipes moved to
  Postgres when accounts, editing, visibility, and collaboration made that constraint expensive
* **Less is more** — the product still reuses the personal site's frontend and delivery path while introducing
  dedicated workers only for shared state and durable ingestion
* **Sequence dependencies, parallelize surfaces** — identity and persistence are genuine critical paths; kitchen,
  cooking, discovery, and design work can advance concurrently around stable contracts

## Hypothesis-Led Delivery

The project cannot outspend large commercial teams, but it can maintain a tighter loop between a real pain point,
a small intervention, and observed use. Broad feature coverage is not evidence of product-market fit. Each part
of the lifecycle should advance through a falsifiable ladder before the next layer depends on it.

For passive nutrition, that ladder is:

1. Structured ingredients produce recipe and serving estimates credible enough to influence a choice.
2. Completing a cook proposes the right meal and portion often enough that confirmation is easier than logging.
3. Substitutions, shared portions, and leftovers can be corrected in seconds, not reconstructed ingredient by
   ingredient.
4. The resulting history changes a later plan, basket, recipe adaptation, or repeat decision often enough to be
   useful.
5. Only then should photos, barcodes, or AI address the remaining unstructured meals—and they must beat the
   correction burden of the simpler fallback.

Apply the same discipline elsewhere: validate that synchronized lists reduce coordination before adding many
retailers; validate that one basket integration reaches checkout before building adapters; validate that public
cook and repeat signals improve discovery before inventing a complex ranking model; validate that taste-neighbour
recommendations lead to successful novel cooks before generating algorithmic communities. Useful metrics include
accept-without-edit rate, median correction time, completed journeys, recommendation cook-through, repeat use,
plan-to-cook conversion, actual versus expected effort, leftover use, and cuisines or techniques newly cooked—not
click-through rate, viewing time, or the number of AI-powered surfaces shipped. No single metric should define
value: repeat cadence identifies staples, while explicit enjoyment and occasion context preserve recipes worth
making rarely.

# Risks

## Cold start and weak network effects

A public graph is not valuable merely because the schema exists. With few cooks, follows, or repeated meals,
"social" ranking will be sparse and aggregate percentages will be misleading. Household utility can
retain users, but it cannot validate the public flywheel by itself.

**Mitigation:** Test with connected friend and family cohorts rather than isolated accounts. Seed useful public
collections, make publishing and following natural extensions of existing cooking, and measure whether recipes
travel through save → plan → cook → repeat. Do not display percentages without meaningful denominators.

## Signal quality and incentives

Cook-mode starts are not cooked meals, repeats are not necessarily endorsements, and public metrics invite
gaming once they affect discovery. A neat-looking activity score could become less honest than the reviews it
was meant to improve.

**Mitigation:** Keep event definitions explicit, show the evidence behind rankings, separate intent from action,
rate-limit implausible activity, and let qualitative notes explain outcomes. Optimize for successful cooking and
useful adaptations rather than feed engagement. Add moderation and abuse controls in proportion to public reach.

## Taste bubbles and popularity feedback

Collaborative filtering can make a food bubble more confident instead of helping somebody escape it. Popular
recipes collect more outcome data, similar cooks reinforce one another, and new recipes or cuisines struggle to
enter the candidate pool. A community inferred from behaviour can also feel reductive if treated as identity.

**Mitigation:** Separate candidate generation from ranking, reserve an explicit exploration budget, normalize
for exposure, and let users tune familiarity versus novelty. Explain which shared tastes form the bridge, never
label an inferred cohort as identity without consent, and measure successful new cuisines, ingredients, and
techniques alongside immediate cook-through and repeat rate.

## Frequency bias and contextual stereotyping

Observed behaviour can create a different bad proxy if frequent, easy meals always outrank ambitious or
special-occasion food. It can also mistake circumstances for identity: a period of low-effort cooking does not
prove somebody's occupation, health, mobility, family role, or long-term preference.

**Mitigation:** Keep deliciousness, practicality, effort, occasion, and repeat evidence separate; use
multi-objective ranking and ask for current context when it materially changes a recommendation. Prefer declared
constraints over inferred personal attributes, keep behavioural inference narrow and revisable, explain why a
recipe was suggested, and let people correct it. Evaluate whether the system serves both reliable routines and
occasional aspiration rather than maximizing frequency alone.

## Adoption friction

The primary users no longer choose only between this and the physical book. Tandoor, Samsung Food, Paprika, and
others offer mature personal workflows; no social vision excuses a worse everyday tool. Poor connectivity,
browser-local planning, missing retailer hand-off, or excessive nutrition logging can break the journey before
the network receives a useful signal.

**Mitigation:** Test complete journeys during real shopping and cooking sessions, not isolated screens. Prioritize
server-backed household planning, shopping hand-off, passive nutrition, and offline continuity, then optimize the
messiest moments—choosing under time pressure, matching products, hands covered in flour, a timer going off, and
three things on the stove.

## Nutrition accuracy and logging burden

Ingredient normalization, serving assumptions, substitutions, leftovers, restaurant meals, and shared dishes
make passive nutrition approximate. Asking users to resolve every ambiguity would recreate the food-log burden
that made ZOE difficult to sustain; hiding the uncertainty would create false confidence.

**Mitigation:** Use nutrition for directional planning rather than clinical claims, show assumptions and ranges,
ask only high-impact questions, and let users correct exceptions quickly. Track accept-without-edit rate and
median correction time; if a photo or barcode flow creates ingredient-level reconstruction work, it has failed
regardless of model accuracy in a benchmark. Measure whether guidance changes plans, baskets, and repeat
cooking—not whether users maintain an artificial logging streak.

## Retail integration brittleness

Retailer catalogs, product identifiers, availability, authentication, and partner APIs vary by region and change
outside this project's control. A failed product match at checkout can erase the convenience gained earlier in
the journey.

**Mitigation:** Keep the canonical ingredient and shopping models retailer-independent. Begin with one strong
partner path, make every match reviewable, retain manual and export fallbacks, and expand only when completed
baskets justify the maintenance cost.

## Content migration effort

The physical collection and potential users' existing app libraries contain many more recipes than a one-at-a-time
flow can comfortably absorb. Extraction quality alone does not solve grouping, duplicates, correction, retries,
or whole-batch recovery.

**Mitigation:** Keep improving the evaluated photo pipeline, but measure migration time through the entire review
journey. Build the durable batch workspace before adding a long tail of formats or noisy social sources.

## Feature creep

The feature list above is ambitious. Building everything before shipping anything would violate
every principle in the building philosophy.

**Mitigation:** Maintain a small critical path and bounded parallel tracks. New ideas must strengthen a current
journey, close a measured competitive gap, or provide a reusable foundation; they do not earn priority merely by
appearing on a competitor's feature list.

## Architecture Decision Records

- [ADR 000: Github Public Repo](https://robbiepalmer.me/projects/recipe-site/adrs/000-github-public-repo.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 001: Monorepo](https://robbiepalmer.me/projects/recipe-site/adrs/001-monorepo.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 002: React](https://robbiepalmer.me/projects/recipe-site/adrs/002-react.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 003: Next.js](https://robbiepalmer.me/projects/recipe-site/adrs/003-next-js.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 004: Mise En Place](https://robbiepalmer.me/projects/recipe-site/adrs/004-mise.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 005: Tailwind CSS](https://robbiepalmer.me/projects/recipe-site/adrs/005-tailwindcss.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 006: Turbopack](https://robbiepalmer.me/projects/recipe-site/adrs/006-turbopack.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 007: Pnpm](https://robbiepalmer.me/projects/recipe-site/adrs/007-pnpm.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 008: Vitest](https://robbiepalmer.me/projects/recipe-site/adrs/008-vitest.md) — Accepted, 2025-10-18 (inherited from personal-site)
- [ADR 009: CodeRabbit](https://robbiepalmer.me/projects/recipe-site/adrs/009-code-rabbit.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 010: Terraform](https://robbiepalmer.me/projects/recipe-site/adrs/010-terraform.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 011: Cloudflare Pages](https://robbiepalmer.me/projects/recipe-site/adrs/011-cloudflare-pages.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 012: Claude Code](https://robbiepalmer.me/projects/recipe-site/adrs/012-claude-code.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 014: Husky Precommit](https://robbiepalmer.me/projects/recipe-site/adrs/013-husky-precommit.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 015: Static Site Generation](https://robbiepalmer.me/projects/recipe-site/adrs/014-ssg.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 016: GitHub Actions](https://robbiepalmer.me/projects/recipe-site/adrs/015-github-actions.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 017: Terraform Cloud](https://robbiepalmer.me/projects/recipe-site/adrs/016-terraform-cloud.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 018: GitHub Secrets](https://robbiepalmer.me/projects/recipe-site/adrs/017-github-secrets.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 019: Shadcn](https://robbiepalmer.me/projects/recipe-site/adrs/018-shadcn.md) — Accepted, 2025-10-19 (inherited from personal-site)
- [ADR 022: Fuse.js](https://robbiepalmer.me/projects/recipe-site/adrs/019-fuse-js.md) — Accepted, 2025-10-26 (inherited from personal-site)
- [ADR 024: Renovate](https://robbiepalmer.me/projects/recipe-site/adrs/020-renovate.md) — Accepted, 2025-11-02 (inherited from personal-site)
- [ADR 028: Cloudflare DNS](https://robbiepalmer.me/projects/recipe-site/adrs/021-cloudflare-dns.md) — Accepted, 2025-11-26 (inherited from personal-site)
- [ADR 029: Cloudflare Images](https://robbiepalmer.me/projects/recipe-site/adrs/022-cloudflare-images.md) — Accepted, 2025-12-14 (inherited from personal-site)
- [ADR 030: Downgrade Cloudflare Terraform Provider](https://robbiepalmer.me/projects/recipe-site/adrs/023-downgrade-cloudflare-tf.md) — Accepted, 2025-11-26 (inherited from personal-site)
- [ADR 032: CodeQL](https://robbiepalmer.me/projects/recipe-site/adrs/024-codeql.md) — Accepted, 2025-12-18 (inherited from personal-site)
- [ADR 033: In-Memory Content Graph](https://robbiepalmer.me/projects/recipe-site/adrs/025-content-graph-indexes.md) — Accepted, 2025-12-30 (inherited from personal-site)
- [ADR 034: Shortcut](https://robbiepalmer.me/projects/recipe-site/adrs/026-shortcut.md) — Accepted, 2025-12-28 (inherited from personal-site)
- [ADR 037: AGPL-3.0 License](https://robbiepalmer.me/projects/recipe-site/adrs/027-agpl-license.md) — Accepted, 2026-01-11 (inherited from personal-site)
- [ADR 040: PostHog Analytics](https://robbiepalmer.me/projects/recipe-site/adrs/028-posthog-analytics.md) — Accepted, 2026-02-14 (inherited from personal-site)
- [ADR 029: DVC](https://robbiepalmer.me/projects/recipe-site/adrs/029-dvc.md) — Accepted, 2026-02-21
- [ADR 030: Cooklang](https://robbiepalmer.me/projects/recipe-site/adrs/030-cooklang.md) — Accepted, 2026-03-01
- [ADR 031: OpenRouter](https://robbiepalmer.me/projects/recipe-site/adrs/031-openrouter.md) — Accepted, 2026-05-23
- [ADR 032: Better Auth](https://robbiepalmer.me/projects/recipe-site/adrs/032-better-auth.md) — Accepted, 2026-05-25
- [ADR 033: Backend Platform for Authenticated Features](https://robbiepalmer.me/projects/recipe-site/adrs/033-backend-platform-for-authenticated-features.md) — Accepted, 2026-05-27
- [ADR 034: Authorization Model](https://robbiepalmer.me/projects/recipe-site/adrs/034-authorization-model.md) — Accepted, 2026-05-27
- [ADR 035: Application Security Baseline](https://robbiepalmer.me/projects/recipe-site/adrs/035-application-security-baseline.md) — Accepted, 2026-05-27
- [ADR 036: Google OIDC Login](https://robbiepalmer.me/projects/recipe-site/adrs/036-google-oidc-login.md) — Accepted, 2026-06-19
- [ADR 037: GitHub OAuth Login](https://robbiepalmer.me/projects/recipe-site/adrs/037-github-oauth-login.md) — Accepted, 2026-06-19
- [ADR 041: Gemini Code Assist](https://robbiepalmer.me/projects/recipe-site/adrs/038-gemini-code-assist.md) — Deprecated, 2026-06-20 (inherited from personal-site)
- [ADR 042: Greptile](https://robbiepalmer.me/projects/recipe-site/adrs/039-greptile.md) — Accepted, 2026-06-20 (inherited from personal-site)
- [ADR 043: Codex](https://robbiepalmer.me/projects/recipe-site/adrs/040-codex.md) — Accepted, 2026-06-21 (inherited from personal-site)
- [ADR 044: Codex Code Review](https://robbiepalmer.me/projects/recipe-site/adrs/041-codex-code-review.md) — Accepted, 2026-06-21 (inherited from personal-site)
- [ADR 045: Qodo](https://robbiepalmer.me/projects/recipe-site/adrs/042-qodo.md) — Deprecated, 2026-06-21 (inherited from personal-site)
- [ADR 046: Custom Agentic Code Review](https://robbiepalmer.me/projects/recipe-site/adrs/043-custom-agentic-code-review.md) — Deprecated, 2026-06-21 (inherited from personal-site)
- [ADR 047: Trivy Security Scanner](https://robbiepalmer.me/projects/recipe-site/adrs/044-trivy.md) — Accepted, 2026-06-21 (inherited from personal-site)
- [ADR 045: SonarQube](https://robbiepalmer.me/projects/recipe-site/adrs/045-sonarqube.md) — Accepted, 2026-06-26
- [ADR 049: Zizmor & actionlint (GitHub Actions Security)](https://robbiepalmer.me/projects/recipe-site/adrs/046-zizmor.md) — Accepted, 2026-06-27 (inherited from personal-site)
- [ADR 047: PostHog Logs for Backend Observability](https://robbiepalmer.me/projects/recipe-site/adrs/047-posthog-logs.md) — Accepted, 2026-06-28
- [ADR 048: Cloudflare Workers Observability Destinations (Beta)](https://robbiepalmer.me/projects/recipe-site/adrs/048-cloudflare-observability-destinations.md) — Accepted, 2026-06-28
- [ADR 049: Cloudflare Workflows for Recipe Ingestion](https://robbiepalmer.me/projects/recipe-site/adrs/049-cloudflare-workflows-recipe-ingestion.md) — Accepted, 2026-07-08
- [ADR 050: Cloudflare Access for Preview Environment Gates](https://robbiepalmer.me/projects/recipe-site/adrs/050-cloudflare-access-preview-gates.md) — Accepted, 2026-07-08
- [ADR 051: Neon Database Snapshots and Encrypted R2 Backups](https://robbiepalmer.me/projects/recipe-site/adrs/051-neon-database-snapshots-and-backups.md) — Accepted, 2026-07-13
- [ADR 051: Relational Notification Events and Subtypes](https://robbiepalmer.me/projects/recipe-site/adrs/051-relational-notification-events.md) — Accepted, 2026-07-15
- [ADR 052: Committed PostgreSQL Migrations and Data Operations](https://robbiepalmer.me/projects/recipe-site/adrs/052-committed-postgres-migrations.md) — Deprecated, 2026-07-17
- [ADR 053: Fresh Migration Baseline and Isolated Preview Database Project](https://robbiepalmer.me/projects/recipe-site/adrs/053-fresh-migration-baseline-and-isolated-preview-database-project.md) — Accepted, 2026-07-18
- [ADR 054: TanStack Query for Client-Side Server State](https://robbiepalmer.me/projects/recipe-site/adrs/054-tanstack-query-for-client-server-state.md) — Accepted, 2026-07-19
- [ADR 051: TFLint (Terraform Linting)](https://robbiepalmer.me/projects/recipe-site/adrs/055-tflint.md) — Accepted, 2026-07-20 (inherited from personal-site)
- [ADR 052: Knip (Dead Code & Dependency Hygiene)](https://robbiepalmer.me/projects/recipe-site/adrs/056-knip.md) — Accepted, 2026-07-20 (inherited from personal-site)
- [ADR 053: OpenSSF Scorecard (Repo Security Posture)](https://robbiepalmer.me/projects/recipe-site/adrs/057-openssf-scorecard.md) — Accepted, 2026-07-20 (inherited from personal-site)
- [ADR 054: Gitleaks (Secret Scanning)](https://robbiepalmer.me/projects/recipe-site/adrs/058-gitleaks.md) — Accepted, 2026-07-20 (inherited from personal-site)
- [ADR 055: typos (Spell Checking)](https://robbiepalmer.me/projects/recipe-site/adrs/059-typos.md) — Accepted, 2026-07-20 (inherited from personal-site)
- [ADR 061: Agent Auth for Delegated Recipe Access](https://robbiepalmer.me/projects/recipe-site/adrs/061-agent-auth.md) — Proposed, 2026-07-25
- [ADR 062: Direct OTLP Export to PostHog Without a Collector](https://robbiepalmer.me/projects/recipe-site/adrs/062-direct-otlp-export-to-posthog.md) — Accepted, 2026-07-25
- [ADR 063: PostHog Alerting and Lightweight Incident Management](https://robbiepalmer.me/projects/recipe-site/adrs/063-posthog-alerting-and-slack.md) — Accepted, 2026-07-29
- [ADR 064: Realtime Household Collaboration with Durable Objects](https://robbiepalmer.me/projects/recipe-site/adrs/064-realtime-household-collaboration.md) — Proposed, 2026-07-30
- [ADR 065: Spectral (OpenAPI Linting & API Governance)](https://robbiepalmer.me/projects/recipe-site/adrs/065-spectral.md) — Accepted, 2026-08-09
- [ADR 066: Batch Recipe Import Staging](https://robbiepalmer.me/projects/recipe-site/adrs/066-batch-recipe-import-staging.md) — Proposed, 2026-08-08

---

Markdown index of this site: https://robbiepalmer.me/llms.txt