01 — Overview
The problem this solves
I have a Whole Foods Chantilly cake recipe saved on my computer, with my own notes on it. I've never made it again. By the time I'm in the kitchen with my phone, finding that file is more friction than just searching online — and the version I find isn't the same. The barrier to cooking with my good recipes is sufficiently high that I choose YouTube instead, simply for convenience.
The recipes aren't gone. They're stranded. Heirloom brings them home.
The problem isn't storage format. It's that the friction of retrieval broke the habit of returning to recipes people already love. Heirloom solves two things: it rescues existing recipes from wherever they're living, and it surfaces them at the moment you're ready to cook — by ingredient, by what's about to go bad, by what you haven't made in a while.
02 — Users
Two people with the same problem, different recipes
Both primary users have a collection of recipes they love but rarely cook from, because retrieving them is more friction than just finding something online. Their recipes are stranded in different places — but the failure mode is identical.
The digital archivist
Has years of recipes saved as PDFs, Word docs, and text files — on a desktop, in a downloads folder, maybe in email attachments. Technically comfortable. The barrier is steps, not skill: getting the file from computer to kitchen requires too many of them.
Primary import path
Bulk file upload from a folder. Wants to bring everything in at once and sort it out from there.
The keeper of cards
Has a shoebox or binder of recipe cards — some in their own handwriting, some in a parent's or grandparent's. Deeply attached to them. The barrier is physical: the cards live in a drawer, not in the kitchen, and finding the right one takes digging.
Primary import path
Photo capture, one recipe at a time. Each import is a small act of preservation, not a bulk transfer.
Design constraint
This app is built for people who already know how to use their recipes. It doesn't teach cooking. It removes the friction between a good recipe and the moment someone is ready to make it.
03 — Goals
What success looks like
Standard engagement metrics — session length, daily actives — aren't the right measure here. The job is re-engagement: people cooking from recipes they already love but stopped reaching for. These metrics measure that.
< 20%
of recipe imports require manual correction. Parsing should handle the common cases; manual correction is the exception.
90%
of users return to import more recipes after their first correction experience. The correction flow must feel fast and forgiving, not punishing.
10+
recipes imported by the average user in their first month. A library too small to search from is a library that won't be used.
≥ 90%
parsing confidence considered a successful import. Below this threshold, recipes are flagged for review.
Cooked
At least one recipe is prepared and photographed from within the app. This is the moment the product actually worked.
04 — Non-Goals
What this is not
Not a shopping app. Recipe ingredients are not forwarded to a grocery store or shopping list service.
Not a cooking teacher. Built for users who already know how to use their recipes. No technique explanations, no beginner guidance.
Not a pantry manager. The app doesn't scan or track what's in your pantry — ingredient search is user-entered, not pantry-synced.
Not a social platform. Single-user in v1. No sharing, no social features, no public recipes.
05 — Re-engagement
Surfacing recipes at the right moment
Import solves the rescue problem. Re-engagement solves the return problem. Getting recipes onto the phone doesn't automatically rebuild the habit of cooking from them — the app needs to do that work too.
Core re-engagement features
Unified search. A single search surface handles both recipe name lookup and ingredient-based discovery. Typing "Chantilly" surfaces the recipe by name. Typing "chicken, peppers" surfaces recipes by ingredient. Ambiguous queries — like "chicken" — return both recipe name matches and ingredient matches together, letting the user self-select. A toggle on ingredient results allows "match all" vs. "match any." Search is accessible from the home screen, not buried in the library.
What you haven't made lately. Lightweight surfacing on the home screen — not algorithmic push notifications, just a quiet reminder. "You haven't made the Chantilly cake in a while." Recipes imported but never cooked rise to the top over time. This is v1's answer to re-engagement; behavior-based surfacing that learns which recipes actually matter to each user is a v2 feature.
Design principle
Unified search doesn't ask users to declare intent upfront. A user who types "chicken" looking for a specific recipe might see an ingredient match they hadn't considered and discover they can make something tonight. Re-engagement happens incidentally — which is the best kind.
06 — Features
Requirements
Privacy
- Usage analytics collected to measure product health — no personally identifiable information included
- Recipe content, ingredients, and user data stored on-device only; never transmitted or sold
Onboarding
- First use opens to a welcome screen that guides the user into importing their first recipe
- Onboarding tone reflects the rescue framing — "bring your recipes home," not "add your first recipe"
- Both import paths (file upload, photo capture) are presented as equal entry points
Recipe Import
Supported formats
- Files: txt, pdf, docx — PDFs may contain images or text; the app recognizes and parses either
- Images: camera capture or photo library
- Bulk upload: all files in a folder imported at once; successful imports, flagged imports, and failed imports surfaced separately
Parsing intelligence
- Handles imprecise quantities: "a pinch," "a bunch," "to taste"
- Parses preparation notes: "1 clove of garlic, minced"
- Parses user notes: "Next time, more sugar" — stored separately from recipe steps
- Understands ingredient synonyms: green onions, scallions, and spring onions are the same thing
- Common ingredients pre-loaded; new ingredients added as recipes are converted
- Parses individual recipe steps and links each step to the ingredients it requires
- If a scanned recipe matches an existing recipe at ≥ 95%, flagged for user review before insertion
Manual corrections
- Recipes imported below confidence threshold are flagged for review — not discarded
- Correction screen highlights uncertain ingredients or steps in the UI
- User can: accept as-is, edit and finalize, or skip for later
- Once accepted, the "needs attention" flag is cleared
- When opened from the import screen, the next flagged recipe loads automatically
Failed import recovery
- Recipes that cannot be parsed with significant confidence added to a recovery queue
- Queue displayed immediately after import
- Retry mode: deeper scan experience, similar to check scanning in a banking app — app parses the image at capture time
- User decides per recipe: retry, skip, or discard
Recipe List
- Default view shows all imported recipes without filters
- Recipes needing manual attention displayed with visible indicator
- Recipes not yet cooked surfaced separately or highlighted — supports the re-engagement goal
- Recipe opened by a single tap
- Scroll position remembered — exiting a recipe returns to last position in list
- Recipe photo (if taken) used as card image in list view
Unified Search
Recipe name search
- User types a recipe name or partial name; library returns matching recipes immediately
- Accessible from home screen — primary navigation tool for users who know what they want to make
- Results drawn from the user's library only, never a generic database
Ingredient search
- User enters ingredients on hand as chips; app searches their library for matching recipes
- Toggle: match all entered ingredients vs. match any
- Results ranked by match quality; partial matches visible with missing ingredients noted
- Re-engagement entry point — for users who don't know what they want to make yet
Unified results
- Ambiguous queries — a single word like "chicken" — return both recipe name matches and ingredient matches in the same results view, grouped by type
- User self-selects which result is relevant; no upfront intent declaration required
- A user searching by name may discover an ingredient match they hadn't considered — re-engagement happens incidentally
Cooking from a Recipe
- Opening a recipe that needs manual attention begins with the correction screen — user can correct, skip, or cancel
- Cooking screen opens to an ingredients view for prep before cooking begins
- Steps view shows one step at a time — no accidental scrolling through the recipe
- On each step, a gesture surfaces the ingredients pertinent to that step as an overlay or split panel
- Volume-to-weight conversion available by ingredient when the user enters a conversion factor; toggleable on the main recipe screen
- Gesture to capture notes during cooking — attached to the recipe
- Recipe editable during cooking; edits saved
- Photo of the finished meal can be taken from within the cooking screen; attached to the recipe and used as the list card image
07 — Open Questions
What needs to be resolved
Architectural — bulk import surface
Bulk upload from a desktop folder implies a web interface. The current spec is mobile-only. This is an unresolved architectural decision: does Heirloom become a two-surface product (web for bulk import, mobile for cooking), or is mobile bulk import solvable without a separate web app? Decision deferred to v1 planning.
What happens when a recipe cannot be parsed at all — no recognizable structure? Added to failed queue, or discarded immediately?
What does the app do when the scanned document is not a recipe? Error state, or a graceful redirect to manual entry?
Recipes written in a foreign language — how does this affect ingredient synonym lists and preparation method parsing?
Two ingredients in a recipe share a name but have different preparations — e.g., "butter, softened" and "butter, melted." How does the parser distinguish them?
If the user never completes manual correction, does the recipe remain in a flagged state indefinitely? Is there a time-based resolution?
Is the effort of conversion worth it even with some manual correction required? This is the core adoption risk — the correction experience must not feel like work.
Export and backup — full library export to a standard format (JSON, PDF, or both) for backup and device migration. Recipes are personal data with real sentimental value; losing them to a lost phone is unacceptable in a mature product.
08 — Out of Scope / V2
Noted for later
Recipe scaling
Ingredient substitutions ("vinegar in milk if you don't have buttermilk")
Pantry entry and management
Camera-based pantry scanning
Parallel step parsing — identifying steps two people could do simultaneously
Voice recognition for hands-free cooking
Recipe albums and collections
Social features — single recipe sharing and album sharing