# Memory-First Calorie Tracking App
*Living Product Vision Document (v0.2)*

# Vision
Build the most frictionless calorie tracking app for serious nutrition users.

It answers three questions:
1. Today — What should I do next?
2. Food — What did I record on this day?
3. Journal — How is my plan progressing, and what should I review next?

# Product Principles
- Frictionless logging
- Memory over prediction
- Context beats search
- Capture once, reuse many times
- Show progress, not just numbers
- Explainable recommendations
- Progressive disclosure
- Privacy by default
- Celebrate consistency over perfection
- Holistic health
- User owns their data
- Reduce uncertainty
- Protect data integrity over data volume

# Core Jobs to be Done

## Daily
- Track food with minimal friction.
- Understand today's calorie and protein status.
- Know the next best action.

## Weekly
- Understand whether the plan is working.
- Validate incomplete data before algorithm adjustments.

## Long-term
- Discover behavioural patterns.
- Connect body changes with nutrition.

# Onboarding Flow

```mermaid
graph TD
    A[Start: Sign In / Sign Up<br/>Continue with Apple authenticates only] --> B[Body Data: Enter Manually or Choose Apple Health Assist]
    B --> C{Use Apple Health to Fill Available Data?}
    C -->|Yes| D[Explain Requested Data and Show Apple Health Permission]
    D --> E[Confirm or Edit Available Height and Weight<br/>Enter Missing Fields and Equation Sex Manually]
    C -->|No| F[Enter Age, Height, Weight, Units, and Equation Sex Manually]
    D -->|Denied or Limited| F
    E --> G[Run Safety Screen]
    F --> G
    G --> H[Select Goal: Lose, Maintain, Gain, Recomposition]
    H --> H2[Set Goal Destination: Landing Weight or Recomposition Body Fat<br/>Recomposition May Explicitly Defer]
    H2 --> I{Recent Apple Health Activity Available?}
    I -->|Yes| J[Prefill Activity from Available Steps and Workouts<br/>Person Confirms or Edits]
    I -->|No| K[Request Apple Health Separately or Ask Activity Manually]
    J --> L[Calorie Target: Recommend or Manual]
    K --> L
    L --> M[Confirm Starting Target]
    M --> N[Acknowledge Setup: Goal, Destination or Deferred State, and Starting Point]
    N --> O[Go to Today]
    O --> P[Today Home: Food Logging Is a Primary Action]
```

Continue with Apple is an account-authentication method. It does not grant Apple Health access. Apple Health assist is optional and uses a separate, contextual permission request.

Only available, permitted values can prefill onboarding. Imported body data and activity remain editable and require confirmation. Missing or limited access falls back to manual fields. The private equation-sex input is never silently sourced from Apple Health and retains its existing explanation and privacy handling.

Manual weight entry uses one direct numeric field with a decimal keypad and a clear, visible kg/lb control. Formatting follows the person’s locale, and validation occurs on commit after allowing normal partial input while editing. Rejected wheel and hybrid concepts do not appear as alternatives in the onboarding flow.

## Goal destination

Every goal asks where the person wants the plan to land:

| Goal | Destination input | Rule |
|---|---|---|
| Lose | Landing weight | Must be below the confirmed current weight and must not imply a target BMI below the approved safety boundary. |
| Maintain | Landing weight | Defaults near the confirmed current weight. A materially lower or higher selection prompts the person to choose Lose or Gain instead. |
| Gain | Landing weight | Must be above the confirmed current weight. Choosing a higher destination never increases the initial surplus beyond the approved gain logic. |
| Recomposition | Landing body-fat percentage | Acts as a progress reference only. It does not calculate calories or promise a body-composition outcome. |

The destination screen uses a coarse, accessible slider paired with one synchronized editable numeric value and a programmatically announced kg/lb or percentage unit. The numeric value follows locale formatting and is the precision control. Changing either control updates the same stored value, accessible announcement, validation state, and CTA. The person can use direct entry instead of dragging.

Weight slider bounds are personalized from the confirmed current weight, units, goal direction, and safety rules. Exact product maxima remain subject to validation.

Recomposition asks for the current body-fat estimate and its measurement source before accepting a landing percentage. Comparisons use compatible methods. If the person has no credible estimate or does not want to set one, they can set it later and continue with measurements, training evidence, and weight context. The app must not invent body fat or diagnose whether a percentage is healthy.

A landing destination expresses intent; it is not a promised outcome. It does not override pace caps, intake floors, evidence requirements, clinical exclusions, or manual-only status.

Destination validation reruns goal-direction and safety eligibility before target review. Direct entry cannot bypass slider limits, the target-BMI boundary, or the manual-only outcome. Maintain’s exact landing band remains unresolved; until it is approved, the destination is locked to the current confirmed weight, the slider is disabled, and a lower or higher intent routes to Lose or Gain. Recomposition’s slider and confirmation action also remain disabled until clinical bounds are approved; “Set later and continue” is the available fallback.

After the person confirms a recommended or manual target, onboarding acknowledges setup completion with neutral copy such as “Your starting plan is ready” and “You’ve taken the first step: your goal, destination, and starting point are set.” If a Recomposition destination was explicitly deferred, use “Your goal and starting point are set. You can add a body-fat destination later.” Each acknowledgement screen has exactly one CTA: **Go to Today**. There is no plan-review action and no log-now/log-later decision. The manual-only path preserves the user-entered source and never reframes it as a recommendation. Food logging is available as a primary action after arrival on Today, outside the onboarding flow.

## Setup acknowledgement requirements

1. Show the acknowledgement immediately after the person confirms their starting target.
2. Preserve two variants: eligible recommendation and manual-only.
3. Keep the eligible variant neutral; it confirms that the reviewed estimate is set without repeating the target details.
4. Keep the manual-only variant explicit that the target remains user-provided and will not receive automated recommendations or weekly adjustments.
5. If the Recomposition destination was deferred, acknowledge that explicit state without implying a destination value was set.
6. Show exactly one CTA on either variant: **Go to Today**.
6. Route both variants directly to Today with no plan-review, log-now, or log-later branch.
7. Present food logging as a primary action on Today, outside onboarding.

# Initial Recommendation Algorithm

The first recommendation estimates maintenance calories, then applies goal-specific logic:

- **Lose:** default to 0.5% body weight loss per week, capped at a 20% or 750 kcal daily deficit.
- **Maintain:** begin at estimated maintenance with no deficit or surplus. Detailed maintenance adjustment rules remain a product proposal pending validation.
- **Gain:** add a conservative 5–10% surplus based on resistance-training experience.
- **Recomposition:** begin at estimated maintenance, or offer a 5–10% deficit when fat loss is the explicit priority.

The algorithm uses the 2023 National Academies adult energy equations as the default estimate, Mifflin–St Jeor as a cross-check, and validated food and weight trends to refine the result over time.

If the safety screen makes a person ineligible for automation, the app must not show an automated target for any goal, including Maintain. Neutral food logging remains available with a manual target and appropriate clinical direction.

The app must show the estimate’s range, evidence, and confidence. It must validate incomplete days before proposing a change and let the user accept, defer, reject, edit, or undo it.

See [Initial Nutrition Recommendation Algorithm v0.1](recommendation-algorithm-v0.1.md) for the research, formulas, guardrails, pseudocode, worked examples, and validation plan.

# Information Architecture

The bottom bar contains four destination tabs and one persistent centre action in this order:

`Today | Food | + | Journal | Settings`

The centre `+` is not a fifth tab. It is the fastest action for recording food and opens Food Log directly.

| Position | Owner | Primary responsibility |
|---|---|---|
| Today | Live decision surface | Show today's calorie and macro state, current-week context, current food summary, and the next useful tracking action. |
| Food | Authoritative daily record | Show and edit the itemized food diary for today or a past date, including reconciliation and selected-item actions. |
| `+` | Recording action | Open Food Log with Search, Scan, and Voice available without an intermediate route chooser. |
| Journal | Longitudinal progress and plan | Show completed weeks, Weekly check-in, measures, premium progress photos, plan evidence, new-plan creation, and algorithm reset. |
| Settings | Account and app controls | Manage account, units, integrations and permissions, notifications, personalization controls, subscription state, privacy, export, and deletion. |

The boundaries are:

- Today shows the live week while it can still inform today's choices. Journal owns completed weeks and Weekly check-in.
- Today may summarize recently recorded food. Food remains the authoritative editor and archive for every item.
- Food may display weight, body fat, steps, and training as day context. Journal owns creating and editing body measurements.
- Journal owns plan content and lifecycle. Settings does not own plan review, new-plan creation, or algorithm reset.
- Settings owns account deletion and record export. Algorithm reset does not delete account or user records.

## Non-food capture routes

- Alcohol recorded as a consumed item belongs in Food.
- Weight, body composition, and supported circumference measurements are created and edited in Journal.
- Steps and training can arrive from Apple Health when permission exists and remain attributable to their source.
- Manual entry routes for steps, training type/minutes, and qualitative daily notes remain product decisions. These routes must be contextual and must not turn the centre `+` into a generic action menu.

# Today Command Centre

The home screen has a two-layer hierarchy.

## Primary: Today

Today answers:

- Calories remaining
- Protein remaining
- Daily progress
- Start or continue tracking
- Suggested next action
- Helpful insight

The current diary remains legible. The product does not turn an individual day into a moralized score or label it good or bad.

Today may show current foods and meal totals for situational awareness. Opening or editing the detailed record routes to Food.

The bottom bar has a persistent centre `+` action. One tap opens Food Log directly, without an intermediate route-choice sheet. Food Log keeps the meal slot visible and editable, and exposes search, recent and usual meals, barcode, voice, and reusable-meal creation on the destination screen.

Food Log personalizes context without removing control:

- On cold start, local time preselects Breakfast, Lunch, Dinner, or Snack from broad time bands.
- After enough completed logs, the person's private history refines their usual meal windows.
- The person can always change the selected meal, and the product explains why it made the suggestion.
- “Usual around this time” ranks the person's own foods and reusable Meal Templates using frequency, recency, and time context.
- The ranking optimizes logging speed. It does not judge nutrition quality or goal compliance.
- Before enough history exists, the product omits personalized-usual claims rather than fabricating a habit.

Search, Scan, and Voice use one Food Entry page:

- The entry point opens the page with its corresponding mode preselected.
- A top switcher changes mode while preserving the selected meal and date.
- Search shows “Usual around this time” until the person types. Search results replace usuals after the first character.
- Scan opens the camera when permission exists. First use requests permission in context; denied access offers manual barcode entry and Search.
- Voice opens with a prominent record control. The recording creates an editable draft that requires confirmation before adding any food or portion.

## Secondary: This Week So Far

A compact weekly layer summarizes progress while there is still time to act. It shows clearly labelled averages or accumulated totals, data coverage, and progress toward the person's selected weekly intent.

Daily weight and body-composition signals, calories, protein, alcohol, steps, training type and minutes, and qualitative notes roll up as follows:

- **Averages or trends:** weight, comparable body-composition observations, calories per validated day, protein per validated day, and steps per day.
- **Accumulated totals:** alcohol in a defined unit, training minutes, and goal-relevant weekly totals where a weekly intent exists.
- **Categorical or qualitative context:** training-type mix, session count, and selected note themes.

Missing, incomplete, and intentionally untracked days are not zero. Every average or total exposes its coverage. The weekly layer summarizes state; it does not bypass Weekly check-in validation or generate coaching before the evidence supports it.

See [Home Screen Direction](home-screen-direction.md) for the detailed roll-up and data-integrity rules.

# Food Tab

Food is the second top-level tab and the durable day-by-day diary. Today helps a person decide what to do next; Food lets them inspect and act on the detailed record for any date.

The Food tab must:

- provide previous-day, next-day, and direct-date navigation at the top;
- group food log events by meal while keeping every item individually selectable;
- show daily calorie, macro, and available micronutrient totals;
- show the day's general context: steps through the relevant day boundary, weight, and body fat, each with source and time;
- use the same information structure for today and past days.

Micronutrient totals must identify unavailable nutrient data. Missing food fields are not zero.

Selection mode must support:

- combining selected events into a Meal Group without deleting or silently rewriting the source events;
- sharing selected foods, portions, and selected nutrition totals through the native iOS share sheet;
- viewing calorie, macro, and available micronutrient totals for the selected events, with coverage.

The default share payload excludes weight, body fat, notes, and unselected day context. Nothing is sent until the person chooses a system destination.

Saving a Meal Group as a reusable Meal Template is a separate optional action. The product must not treat every historical food event as a reusable meal.

Past days can be reconciled. Review status and intake completeness are independent:

- review status is Open, Reconciled, or Reopened;
- intake completeness is Complete, Incomplete, Intentionally untracked, or Unknown.

A reconciled day may still be incomplete. Reconciliation is reversible, corrections remain traceable, and missing, incomplete, or intentionally untracked data is never converted to zero.

The current-plan start-versus-now summary belongs in Journal, not the Food tab.

# Journal Tab

Journal is the third top-level tab. It owns longitudinal progress and plan management; Food remains the source for itemized daily intake.

The Journal overview must provide:

- week-by-week progress in reverse chronological order, with clearly labelled averages, totals, coverage, check-in status, and accepted plan decisions;
- an entry point to start or continue Weekly check-in for an eligible completed week;
- a measurements area for weight, body composition, circumferences, and other supported measures;
- a private progress-photo area marked as a premium feature, without hiding measurement tracking behind the same premium boundary;
- a current-plan summary and access to its baseline, target origin, formula or manual source, evidence window, and adjustment history;
- access to start a new plan;
- access to reset the recommendation algorithm through a separate destructive confirmation flow.

Journal does not merge Weekly check-in with day reconciliation. Food reconciliation records whether a day was reviewed. Weekly check-in validates which days and signals can support interpretation or a recommendation.

## Plan lifecycle

Starting a new plan:

1. archives the current plan without deleting its food, measurements, photos, check-ins, or decisions;
2. asks the person to confirm the new goal, its landing destination, baseline inputs, activity context, and target source;
3. creates a new plan only after review;
4. preserves manual-only safety eligibility when automation remains unavailable.

The current-plan review must show which inputs and sources establish the baseline. It also shows the confirmed landing destination and its source, or an explicit “Set later” state for a deferred Recomposition destination. For an automated plan, this includes the confirmed body and activity inputs, formula version, estimate range, goal logic, and later evidence windows. For a manual plan, it shows the user-provided target and never reframes it as an estimate.

New-plan setup repeats the four-goal choice, then reuses the matching goal-destination component and rules from onboarding before baseline, activity, safety, and target review. It does not inherit the previous plan's goal or landing destination without explicit confirmation.

## Reset recommendation algorithm

Reset applies to the current plan's recommendation model. It clears learned calibration and pending automated recommendations, then rebuilds from the current confirmed baseline when the person remains eligible.

Reset must:

- use a dedicated warning screen and explicit confirmation;
- state what will be cleared before confirmation;
- preserve food logs, Meal Templates, measurements, photos, completed check-ins, prior plans, and accepted-decision history;
- preserve the current plan unless the person separately chooses Start a new plan;
- retain an auditable reset event;
- state that clearing the learned calibration cannot be undone;
- show a completion state that confirms which records and safety status were preserved;
- keep automation-ineligible users manual-only, with no automated neutral maintenance estimate.

Reset does not delete the person's account or records. Deleting or exporting data remains a separate Settings function.

Open product decisions: whether reset also clears time-of-day food personalization and which completed evidence windows remain visible to the rebuilt model.

# Settings Tab

Settings is the fourth top-level tab.

Settings must provide access to:

- account and authentication controls;
- units and locale preferences;
- Apple Health and other integration permissions;
- notification preferences;
- food-personalization controls, including reset or disable options once defined;
- subscription and Premium entitlement status;
- privacy controls;
- data export and record or account deletion.

Settings must not duplicate Food's diary, Journal's plan review, new-plan creation, or recommendation-algorithm reset.

# Commercial model

The core tracker stays free. Free includes Today, Food, Journal, and Settings; search and barcode entry; reusable meals; complete history; measurements; plan review; export; and privacy controls.

Individual Premium costs **$4.99 per month** or **$29.99 per year**. The confirmed Premium features are:

1. **AI photo recognition:** a meal photo produces an editable food and portion draft. Nothing enters the diary until the person reviews and confirms it.
2. **Photo Journal:** private progress photos live beside measurements and plan history in Journal. Photos remain private unless the person explicitly exports or shares them.

Duo costs **$49 per year for two people**. It grants Premium to two linked accounts. Linking accounts must not merge goals, portions, diaries, measurements, recommendations, or privacy controls. Core meal sharing remains available without Duo.

The future pricing strategy may include an optional “Buy me a coffee” contribution for free users. It is not a current interface element. Contributing would not unlock features, alter service, or create a subscription.

Trial design, regional storefront pricing, billing implementation, and future Premium features remain open product decisions.

# Daily Logging Flow

Entry points:
- Repeat usual meal
- Voice
- Barcode scanner
- Search

Every confirmed entry creates a Food Log Event. Search and barcode results may create a single event; repeating a Meal Template creates new events linked to the template version used; a confirmed voice draft creates one or more reviewed events.

Food Log Events preserve history and correction provenance. Meal Groups organize selected events. Meal Templates are optional reusable sources that can be repeated, edited as a new version, and shared without rewriting earlier events.

# Weekly Check-in

1. Celebrate consistency
2. Weekly snapshot
3. Validate suspicious/incomplete days
4. Review measurements and optional premium progress photos
5. Explain the evidence without claiming causation
6. Offer at most one recommendation for next week

# Pattern Detection (Future)

Examples:
- Fridays are often incomplete.
- High-protein breakfasts correlate with success.

# Future Vision

- Coach collaboration
- MCP integrations
- AI coaching