# Home Screen Direction

*Confirmed product direction - 25 July 2026*

## Purpose

The app uses two adjacent daily surfaces with distinct jobs:

1. **Today is the decision surface.** Show where the person is today, place this week's averages close enough to inform the next action, and make food tracking obvious.
2. **Food is the daily record.** Show the full food diary for any date, support item-level actions, and preserve the day's nutrition and body/activity context.

This direction is separate from onboarding. The current-plan summary previously assigned to a History tab moves to Journal; it no longer owns the second tab.

## Primary layer: Today

The first viewport answers three questions:

- Where am I today?
- What does this week suggest about my next action today?
- How do I start or continue tracking?

The layer shows today's calorie and macro state, a compact "This week so far" summary, current food consumed, and available micronutrient coverage. The centre `+` provides the explicit start/continue tracking action. Today must not turn the data into a moralized score or label a day as good or bad.

Micronutrients reflect only the foods and nutrient fields actually recorded. The interface shows coverage or unavailable data instead of treating missing nutrient data as zero.

### Primary logging action

The bottom bar has a persistent centre `+` action. One tap opens Food Log directly; the product does not insert a route-choice sheet first.

Food Log exposes:

- a visible, editable meal slot;
- immediate food and meal search;
- recent and usual meals when real history exists;
- barcode and voice entry;
- reusable-meal creation.

The `+` is an action, not a fifth destination tab.

#### Meal-context personalization

Food Log preselects a meal from the person's local time. Broad time bands support cold start. After the person has enough completed logs, their own history refines the usual time window for Breakfast, Lunch, Dinner, and Snack.

The selected meal remains visible and editable. The screen explains why it selected a meal. A saved correction can inform future suggestions.

“Usual around this time” ranks the person's own foods and reusable Meal Templates for the selected meal and moment. Ranking supports speed through personal frequency, recency, and time context; it must not rank foods by perceived nutrition quality or goal compliance.

The product must not fabricate a usual meal before the evidence exists. Cold-start users see search, barcode, voice, and meal creation without a personalized-usual claim. Shared-meal data must not expose or train on another person's private diary.

Open implementation decisions include the minimum history threshold, weekday and weekend patterns, time-zone changes, shift-work handling, history decay, reset and disable controls, and whether personalization runs on-device or server-side.

#### Unified Food Entry page

Search, Scan, and Voice open one Food Entry page. The tapped entry point determines the preselected mode. A top switcher lets the person change mode without leaving the page or losing the selected meal and date.

- **Search:** With an empty query, show “Usual around this time.” Once the person types, replace usuals with matching results. Clearing the query restores usuals.
- **Scan:** Open the camera immediately when permission exists. On first use, request camera access in context. If access is denied or unavailable, offer manual barcode entry and Search.
- **Voice:** Open with one prominent record control. Request microphone access in context. Convert the recording into an editable draft; do not add interpreted foods or portions until the person reviews and confirms them.

The product must define whether unfinished query text, camera state, or a voice recording persists when the person switches modes.

## Today layer: This week so far

A compact weekly layer sits immediately after today's calorie and macro state, before the food list. It helps the person decide what to do next while there is still time to act.

It shows:

- weekly averages or accumulated totals, labelled by aggregation type;
- progress toward the selected weekly intent;
- data coverage, including which days are complete, corrected, incomplete, or intentionally untracked;
- neutral context from training and notes when it helps explain the record.

The weekly layer is not a miniature Weekly check-in. It summarizes current state. It does not generate a coaching recommendation before the evidence and validation rules allow one.

## Roll-up model

The trainer-sheet concept records daily body, nutrition, movement, training, and qualitative context, then inserts a weekly summary row. The home screen should preserve that distinction.

| Signal | Daily record | Weekly presentation |
|---|---|---|
| Weight | Daily observation | Average and trend; never a total |
| Body composition | Daily observation with source/method | Average or trend only across comparable observations; show observation count |
| Calories | Daily intake on validated tracked days | Average per validated day; show accumulated total only when a weekly calorie intent exists |
| Protein | Daily grams | Average per validated day; show accumulated total when progress toward a weekly protein intent is useful |
| Alcohol | Daily consumption or none recorded | Accumulated total using a defined unit; do not convert it into a moral score |
| Steps | Daily count | Daily average; accumulated total only when a weekly step intent exists |
| Training type | Daily categorical entry | Session count and type mix; not an average |
| Training minutes | Daily minutes | Accumulated total |
| Qualitative notes | Daily free text or structured note | Brief themes or selected context; no sentiment or compliance score |

## Data integrity

- Missing, incomplete, or intentionally untracked days are not zero.
- Every average names its denominator or shows coverage, such as "5 validated days."
- Every accumulated total states the period and included days.
- Body-composition comparisons use compatible measurement methods and expose the source.
- Weekly progress distinguishes observed facts from interpretation.
- Weak or incomplete coverage can result in "keep collecting data" rather than a judgment or recommendation.

## Weekly intent

The secondary layer reflects the person's selected goal - Lose, Maintain, Gain, or Recomposition - without reducing progress to a daily pass/fail state.

Detailed goal-specific weekly progress measures remain a product-design decision. The home screen must preserve the confirmed safety boundary: automation-ineligible users can review their own manual target and recorded data, but do not receive automated target calculations or calorie-change recommendations.

## Food: daily record

Food is the second top-level tab. It answers: "What did I record on this day, and what was the day's context at that point?"

The top date control moves one day at a time and supports direct date selection. The current day remains open. Past days show the same structure after reconciliation:

- food entries grouped by meal, with portions and nutrition;
- daily calorie, macro, and available micronutrient totals;
- steps recorded through the selected point or reconciled day boundary;
- the weight and body-fat observations assigned to that day, with source and time;
- separate review and completeness states.

### Item selection

The person can select one or more food log events. Selection mode supports:

1. **Combine into meal:** group the selected historical events into a named Meal Group without deleting or silently rewriting the underlying log events. Saving that group as a reusable Meal Template is a separate optional action.
2. **Share selected:** present only the selected foods, portions, and selected nutrition totals through the native iOS share sheet by default. Weight, body fat, notes, and unrelated day context stay excluded unless the person explicitly adds them.
3. **View nutrition:** show calorie, macro, and available micronutrient totals for the selected events, including nutrient-data coverage.

### Reconciliation

Reconciliation means the person reviewed the day. It does not mean every intake was captured.

- **Review status:** Open, Reconciled, or Reopened.
- **Intake completeness:** Complete, Incomplete, Intentionally untracked, or Unknown.
- **Signal coverage:** Food, steps, weight, and body-fat availability remain independent.

A reconciled day can therefore remain incomplete. The person can reopen it, make corrections, and reconcile it again. The product retains correction history and never converts missing data into zero.

Open decisions:

- whether date selection uses a calendar, scrubber, or both;
- which micronutrients appear by default and how food-database coverage is summarized;
- whether Meal Groups can span meal slots;
- what metadata and file format the selected-food share item uses;
- when and how the product prompts a person to reconcile an open past day.

## Journal: progress and plan record

Journal is the third top-level tab. It answers: "How is this plan progressing, what needs review, and what is this plan based on?"

Journal owns:

- reverse-chronological weekly progress with coverage and check-in status;
- the Weekly check-in entry point;
- weight, body-composition, circumference, and other supported measurements;
- private progress photos as a premium feature;
- current-plan review, including its baseline inputs, confirmed landing destination, and target source;
- new-plan creation;
- recommendation-algorithm reset.

The week list reports recorded averages, totals, measurement changes, and accepted decisions without turning progress into a grade. Missing days remain missing, and correlations remain possible explanations rather than proof.

Starting a new plan archives the current plan and preserves all history. It repeats the four-goal choice and the matching landing-destination confirmation instead of silently carrying either forward. Lose, Maintain, and Gain use a landing weight; Recomposition uses an optional body-fat destination with a value/source/date observation and a set-later fallback. Current-plan review shows either the confirmed destination or the explicit deferred state. Resetting the recommendation algorithm keeps the current plan and user records but irreversibly clears learned calibration before rebuilding from confirmed inputs. Both actions retain the safety boundary; manual-only users remain manual-only.

## Source

The aggregation model is grounded in `research/benchmark/Thiago Catao_Daily monitoring sheet - Monitoring.pdf`, which records daily weight, body-fat signal, calories, protein, alcohol, steps, training information, training minutes, exercise type, and notes with weekly summary rows.