Nutrition overview

The nutrition feature lives in src/features/nutrition. It renders the coach’s nutrition plan, lets the trainee tick, swap, resize and remove plan foods, add their own meals, and log water. Everything the trainee changes for a day is kept in one Zustand store and synced to the server as a day snapshot. Related pages:

Folder map

Folder	What it holds
`data/`	`types.ts` (DTOs and UI models), `nutritionApi.ts` (every HTTP call and the DTO to model mapping), `calc.ts` (macro math over a plan day plus the trainee’s edits)
`hooks/`	`useNutrition.ts` (React Query hooks and keys), `useNutritionDaySync.ts` (hydrate and debounce-save the day), `useMbp.ts`, `useMealImage.ts`, `useDebouncedValue.ts`
`lib/`	Pure helpers: `portion.ts`, `food-units.ts`, `mbp.ts`, `added-food.ts`, `meal-target.ts`, `meal-target-text.ts`, `day.ts`, `preferred-nutrition-day.ts`, `format.ts`, `macroColor.ts`, `meal-easter-egg.ts`, `id.ts`
`store/`	`nutritionSession.ts`, the day log store (`useNutritionSession`)
`stores/`	`mealDraftStore.ts`, a one-slot draft passed from `meal/add` to `meal/result`
`components/`	Rows, sheets and cards: `MealRow`, `CustomMealRow`, `FoodItemRow`, `AiComponentRow`, `AlternativesSheet`, `AddComponentSheet`, `BarcodeScanSheet`, `MealAiLogger`, `WaterLogger`, `PortionStepper`, `PlanTitlePicker`, `DateNavigator`, `RemainingSummary`, `MenuSummaryCard`, `MealTargetGauge` and others
`presentation/`	The three screens: `PlanScreen`, `MealScreen`, `MealComposerScreen`

Note the two store folders. store/ (singular) holds the day log. stores/ (plural) holds only the meal draft.

Routes

All route files are thin wrappers, except meal/add.tsx and meal/result.tsx, which contain their screens inline.

Route file	Screen	Purpose
`src/app/(app)/(tabs)/nutrition.tsx`	`PlanScreen`	The nutrition tab
`src/app/(app)/meal/[mealId].tsx`	`MealScreen`	One plan meal for the selected date
`src/app/(app)/meal/new.tsx`	`MealComposerScreen`	Compose or edit a trainee’s own meal. Params: `edit`, `plan`, `day`
`src/app/(app)/meal/add.tsx`	`AddMealScreen` (inline)	Quick add: AI photo or text, food search, favorites, history. Param: `mode` (`photo` or `text`)
`src/app/(app)/meal/result.tsx`	`MealResultScreen` (inline)	Review the draft from `meal/add`, adjust, then log it

Plan structure

getNutritionPlan() calls GET /v1/trainee/nutrition and returns an array of plans. A trainee can have several nutrition plans at once.

interface NutritionPlan {
  id: string;
  programName: string | null;
  kind: 'regular' | 'file';
  pdfUrl: string | null;
  autoAlts: boolean;
  targets: NutritionTargetsDto | null;
  days: NutritionDay[];
}

interface NutritionDay {
  id: string;
  label: string;
  targets: NutritionTargetsDto | null;
  meals: NutritionMeal[];
}

interface NutritionMeal {
  id: string;
  type: string;
  label: string;
  time: string;
  prep: string;
  items: NutritionItem[];
  target?: MealTargetDto;
}

interface NutritionItem {
  id: string;
  note: string;
  options: NutritionOption[]; // main option first, then alternatives
}

Mapping rules applied in nutritionApi.ts:

kind comes from planKindOf(plan) in src/features/plans/lib/planKind.ts. The server’s kind wins when present. An older API that only sends pdfUrl still produces a file plan.
autoAlts is true only when the server sends exactly true.
Per-day targets: day.targets ?? plan.targets. A day without its own targets inherits the plan’s.
A meal’s label is the coach’s custom name, else a label looked up by type (breakfast, snack_am, lunch, pre, post, dinner), else a generic meal label.
Each item’s options[0] is the coach’s main food. The rest are alternatives mapped by altOptionOf.
An option’s qtyText is the server’s display.text when present, else qty plus a unit label.
meal.target is only set when the server sends one.

NutritionTargetsDto carries kcal, protein, carbs, fat, water and optional mbpProtein, mbpCarb, mbpFat.

Multiple plans, days and file plans

PlanScreen shows two pickers:

PlanTitlePicker (components/PlanTitlePicker.tsx) switches between plans. It is a plain label when there is one plan and a modal list when there are more. A file plan shows a badge.
PlanSwitcher (src/components/ui/PlanSwitcher.tsx) is a horizontal chip row. On the nutrition tab it is fed the selected plan’s days, not plans, and renders only when the plan has more than one day.

Which plan and day are shown is resolved by resolveNutritionPlanPick and resolveNutritionDayPick in lib/day.ts, in this order:

The trainee’s explicit pick for this date (planPick and dayPick local state, keyed by date).
For today only, the persisted preferred day while it is still active.
The plan day the day’s edits reference most, from referencedDayOf in data/calc.ts.
The first plan and the first day.

See Day log and sync for the preferred day and how the pick reaches the home screen.

File and link plans

src/features/plans/lib/planKind.ts decides what a file plan is and how to show it.

Function	Behaviour
`isFilePlan(plan)`	`kind === 'file'` is true, `kind === 'regular'` is false, otherwise true when `pdfUrl` is a non-empty string
`filePlanSource(url)`	`'pdf'` when the path (query and hash stripped) ends in `.pdf`, or when the url is empty. Otherwise `'link'`
`pdfViewerSource(url, os)`	iOS loads the url directly. Other platforms load it through the Google Docs viewer url, because the Android WebView cannot render a PDF
`planViewerSource(url, os)`	A link loads directly, a PDF goes through `pdfViewerSource`
`pdfCacheName(url)`	Stable `plan-<hash>.pdf` name for the local copy handed to the share sheet
`normalizeFilePlanFlags(raw)`	Reads the home payload’s `filePlan` flags into `training` and `nutrition` booleans

FilePlanView (src/features/plans/components/FilePlanView.tsx) renders the file in a WebView. It has an expand button that opens the shared ContentPdfViewer full screen, and one action button: a link opens in the browser, a PDF is downloaded to the cache directory and passed to the share sheet, falling back to opening the url. FilePlanNotice is the passive card shown where macro progress would normally go. A file plan has no days or meals. When a file plan is selected on an editable day, PlanScreen turns its own scroll off (a WebView needs a bounded height) and shows the water tile, the notice, the file, any meals the trainee added by hand, and the add buttons.

Screens

PlanScreen

presentation/PlanScreen.tsx is the tab. It calls useNutritionDaySync() once and reads the whole session store into a DayEdits object. The body depends on the selected date:

State	What renders
Plan loading	Skeletons
Editable day, regular plan with meals	Water tile and `RemainingSummary`, the day’s `MealRow` list, the trainee’s `CustomMealRow` list, and the add buttons
Editable day, file plan	File plan layout described above
Editable day, no plan	`WaterLogger` and an empty card
Read-only day with a saved snapshot and a plan	The same meal list rendered from the saved snapshot, with no handlers
Read-only day without a snapshot	The diary: `MenuSummaryCard` and `MealListRow` items from `GET /v1/trainee/nutrition/menu?date=`

An editable day is today or yesterday. DateNavigator disables future dates in its calendar. The macro header is built in the macros memo. Goals are day.targets when the coach set them, else the sum of the day’s planned meals (plannedDayMacros). Consumed is eatenDayMacros. When the studio uses MBP, the four rows show MBP totals instead of kcal and grams. The two add buttons go to /meal/add with mode: 'photo' and to /meal/new with the current plan and day ids. Deleting a meal asks for confirmation with Alert.alert. A trainee meal that has a logId also deletes that meal log through useDeleteMealLog. A plan meal is reset to PLANNED and then marked removed for the day.

MealScreen

presentation/MealScreen.tsx finds the meal by id across every plan and day (findMeal). It shows:

MealMacroSummary with the meal total and what was eaten.
MealTargetGauge when the meal has a coach limit.
AiComponentRow for foods the trainee added to this meal.
FoodItemRow for each plan item that is not removed, with the tick, the swap chip, the amount editor and swipe to delete.
A footer with “mark all eaten” and an AI replace button that opens MealAiLogger in a modal.

A meal the coach left empty but gave a limit is “composed” by the trainee. Opening such a meal on an editable day opens AddComponentSheet automatically after AUTO_OPEN_DELAY_MS (350 ms), once per visit. On a future date the screen shows a lock banner, disables the list and hides the footer.

MealComposerScreen

presentation/MealComposerScreen.tsx builds a trainee’s own meal (CustomMeal). Foods come from AddComponentSheet. Each row has a PortionStepper when the food carries portion context, and three editable macro fields. The header shows “remaining today”: the day goal minus what is already eaten minus the draft. Saving calls upsertCustomMeal(dateKey, meal) and goes back. When editing, the original meal is captured once on mount so a store echo cannot reset the draft.

Endpoints used by the data layer

All paths are relative to the API base and go through apiClient (see API client).

Function	Method and path
`getNutritionPlan`	`GET /v1/trainee/nutrition`
`getItemAlternatives`	`GET /v1/trainee/nutrition/alternatives?planId=&itemId=`
`getNutritionMenu`	`GET /v1/trainee/nutrition/menu` with optional `date`
`getNutritionDay`	`GET /v1/trainee/nutrition/day?date=`
`saveNutritionDay`	`PUT /v1/trainee/nutrition/day`
`getMealHistory`	`GET /v1/trainee/nutrition/history`
`analyzeMeal`	`POST /v1/trainee/nutrition/analyze`
`lookupBarcode`	`GET /v1/trainee/nutrition/barcode/<code>`
`logMeal`, `logQuickMeal`	`POST /v1/trainee/nutrition/log`
`deleteMealLog`	`DELETE /v1/trainee/nutrition/log/<id>`
`getFavorites`, `addFavorite`	`GET` and `POST /v1/trainee/nutrition/favorites`
`removeFavorite`	`DELETE /v1/trainee/nutrition/favorites/<id>`
`searchFoods`	`GET /v1/trainee/nutrition/foods?search=`

Water uses /v1/trainee/water and is documented in Water.

Query keys

Defined in hooks/useNutrition.ts.

Key	Hook	Stale time
`['nutrition', 'plan']`	`useNutritionPlan`	60 s
`['nutrition', 'menu', date or 'today']`	`useNutritionMenu`	30 s
`['nutrition', 'day', date]`	`useNutritionDay`	30 s
`['nutrition', 'favorites']`	`useFavorites`	60 s
`['nutrition', 'history']`	`useMealHistory`	60 s
`['nutrition', 'foods', term]`	`useFoodSearch`, enabled from 2 characters	60 s

useSaveNutritionDay invalidates ['home'] on success, because the home rings read the same day log. useLogQuickMeal and useDeleteMealLog invalidate the menu, the history and ['home'].

Tests

Four Node test scripts in scripts/ load the pure modules with a small TypeScript transpile loader and assert the intended behaviour: test-nutrition-portions.cjs, test-meal-target.cjs, test-added-food-amount.cjs and test-plan-kind.cjs. They use node:test. No package.json script references them by name. See Testing and lint.

​Folder map

​Routes

​Plan structure

​Multiple plans, days and file plans

​File and link plans

​Screens

​PlanScreen

​MealScreen

​MealComposerScreen

​Endpoints used by the data layer

​Query keys

​Tests