Nutrition plan JSON

A nutrition plan is stored in Program.content or ProgramTemplate.content when type is NUTRITION. Like the training plan, the contract is a TypeScript type and a tolerant normalizer, not a Zod schema. Macros are not stored in the plan. Items reference foods by id and quantities, and every reader computes calories and macros from the referenced FoodLibraryItem values (merged with the studio’s FoodLibraryOverride).

Where the contract lives

Repo	File	Role
Backend	`apps/core-api/src/modules/program-templates/nutrition-schema.ts`	Types, `normalizeNutritionContent`, `normalizeMealTarget`, day rotation and water helpers.
Backend	`apps/core-api/src/modules/foods/mbp.ts`	Portion (MBP) math: anchors, `roundMbp`, serving tiers.
Backend	`apps/core-api/src/modules/trainee/nutrition-day.ts`	Parser for the trainee’s day snapshot.
Frontend	`apps/saas/modules/shared/lib/nutrition-schema.ts`	The builder’s mirror.
Mobile	`src/features/nutrition/store/nutritionSession.ts`	Writes the day snapshot. `src/features/nutrition/data/calc.ts` is the arithmetic the backend parser mirrors.

Plan shape

normalizeNutritionContent always returns schemaVersion: 1.

{
  "schemaVersion": 1,
  "meta": { "goal": "deficit", "level": "beginner", "autoAlts": true },
  "days": [
    {
      "id": "nd1",
      "label": "Day 1",
      "targets": {
        "kcal": 1900,
        "protein": 150,
        "carbs": 180,
        "fat": 60,
        "water": 3,
        "mbpProtein": 4.5,
        "mbpCarb": 3,
        "mbpFat": 2,
        "kcalOverride": true
      },
      "meals": [
        {
          "id": "ml_ab12cd3",
          "type": "breakfast",
          "label": "",
          "time": "08:00",
          "prep": "",
          "target": { "kcal": 450 },
          "items": [
            {
              "id": "mi_1a2b3c4",
              "foodId": "FOOD_ID",
              "qty": "150",
              "note": "",
              "countsAs": "protein",
              "alts": [
                { "id": "al_5d6e7f8", "foodId": "OTHER_FOOD_ID", "qty": "120" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

`meta`

Key	Type	Notes
`goal`	`deficit`, `balance`, `surplus`	Defaults to `balance`.
`level`	string	Present only when non-empty.
`autoAlts`	boolean	Always present. When true the trainee is offered automatic alternatives for every item in the plan.
`imported`	`true`	Set by the AI plan import. While true, empty values are preserved: quantity `''`, meal time `''`, zero targets and zero water all mean “missing in the document”.
`source`	string	Human label for the import source.
`draft`	`true`	True until the coach saves from the classic builder.
`goalSet`	boolean	`false` means the imported document carried no goal. Picking one sets it to `true`.
AutoFit keys	string or number	Carried through by `pickAutofitMeta`. See Programs and templates.

`days[]`

Key	Type	Notes
`id`	string	Defaults to `nd1`, `nd2` and so on.
`label`	string	Defaults to the Hebrew for “Day N”.
`targets`	object	This day’s targets.
`meals`	array

A plan with no days normalizes to one empty day. Days rotate around the trainee’s current day. nutritionDayIndexForOffset(dayCount, offset) maps a whole-day distance from today to a day index, wrapping around. Today is always the first day and tomorrow the second.

`days[].targets`

Targets live on each day. The top-level targets key is the legacy shape: when present it seeds every day that has no value of its own.

Key	Type	Default	Notes
`kcal`	number	2000
`protein`	number	150	Grams.
`carbs`	number	200	Grams.
`fat`	number	60	Grams.
`water`	number	3	Litres. `targetsWaterGoalMl` converts to millilitres for the app and returns 0 when unset.
`mbpProtein`, `mbpCarb`, `mbpFat`	number	absent	Portion targets. Present only when finite and greater than 0. A day without its own value inherits the plan-level one. There is no automatic conversion from the gram targets.
`kcalOverride`	`true`	absent	Set once the coach types a calorie target over the one derived from the portion targets.

The defaults are DEFAULT_NUTRITION_TARGETS. On imported content the fallback is all zeros, so a missing target stays visibly missing.

`days[].meals[]`

Key	Type	Notes
`id`	string	Generated as `ml_` plus random characters when missing.
`type`	`breakfast`, `snack_am`, `lunch`, `pre`, `post`, `dinner`	Unknown values become `breakfast`.
`label`	string	Custom meal name. Empty falls back to the type’s label.
`time`	string	`HH:mm`. Defaults by type from `MEAL_TYPE_DEFAULT_TIME`: 08:00, 10:30, 13:00, 16:00, 18:00, 20:00.
`prep`	string	Preparation notes.
`items`	array	The foods.
`target`	object	Optional per-meal limit: `kcal`, `mbpProtein`, `mbpCarb`, `mbpFat`. Each key is present only when finite and greater than 0, `kcal` is rounded to a whole number, and a target with no keys left is removed entirely.

`items[]`

Key	Type	Notes
`id`	string	Generated as `mi_` plus random characters. The day snapshot keys reference it.
`foodId`	string or null	`FoodLibraryItem.id`.
`qty`	string	Quantity in the food’s unit: grams or millilitres, or a piece count for piece foods. Defaults to `"100"`, or `''` on imported content.
`note`	string
`countsAs`	`protein` or `carb`	Optional. For dual-exchange foods such as lentils: which macro this item counts toward.
`alts`	array	The coach’s alternatives for this item.

`items[].alts[]`

Key	Type	Notes
`id`	string	Generated as `al_` plus random characters.
`foodId`	string or null
`qty`	string	The quantity of the alternative that stands in for the item.
`countsAs`	`protein` or `carb`	Optional.

Portions (MBP)

Perform can express a plan in portions instead of grams. A portion of a macro is a fixed number of calories, the studio’s anchor.

Constant	Value	Where
`DEFAULT_MBP_ANCHORS`	protein 180 kcal, carb 160 kcal, fat 180 kcal	`foods/mbp.ts`
`MBP_ANCHOR_MIN_KCAL`, `MBP_ANCHOR_MAX_KCAL`	20, 2000	Bounds on a custom anchor.
`MBP_STEP`	0.05	The rounding grid.

roundMbp(x) snaps a portion count to the 0.05 grid and returns 0 for anything not finite and positive. Use it for every stored or displayed portion value. Anchors are per studio and are read from Studio.settings by readMbpAnchors. Changing an anchor re-prices the food library, which is why a value outside the bounds is refused. See Studio settings JSON. A food’s portions come from its macroType (protein, carb or fat) and its exchange quantities (proteinExchangeQty, carbExchangeQty, fatExchangeQty), or from its servingTiers. Those columns are described in Exercise and food libraries. When a plan has no explicit portion targets, mbpTargets(targets, anchors) converts the gram targets through the anchors, each macro through its own.

Alternatives

There are three sources of substitutes for a plan item:

items[].alts[], picked by the coach.
Automatic alternatives, when meta.autoAlts is true. The backend computes them in apps/core-api/src/modules/trainee/food-alternatives.ts from foods of the same macroType.
The trainee’s own swap for one day, stored in the day snapshot’s swaps map.

A food with showAsAlternative = false is never offered as an alternative anywhere. A food the trainee excluded through Client.foodPreferences is filtered at read time.

`Client.foodPreferences`

Validated by foodPreferencesBody in apps/core-api/src/modules/clients/clients.schema.ts:

{
  "excludedCategoryIds": ["dairy"],
  "excludedFoodIds": ["FOOD_ID"],
  "includedExceptionIds": ["FOOD_ID_ALLOWED_DESPITE_ITS_CATEGORY"]
}

Each list holds up to 5000 ids. Only ids are stored. Names are resolved when the preferences are read.

`NutritionDayLog.data`

One row per trainee per day, unique on (clientId, date). The API accepts any object (saveNutritionDayBody.data is a record of unknown values), so the app owns the shape and the backend parses it defensively with parseDaySnapshot.

{
  "eaten": { "2026-10-07__mi_1a2b3c4": true },
  "swaps": { "2026-10-07__mi_1a2b3c4": "OTHER_FOOD_ID" },
  "removed": { "2026-10-07__mi_9z8y7x6": true },
  "portions": { "2026-10-07__mi_1a2b3c4": { "foodId": "FOOD_ID", "qty": 180 } },
  "mealStatus": { "2026-10-07__ml_ab12cd3": "REPLACED" },
  "replacement": {
    "2026-10-07__ml_ab12cd3": { "name": "Restaurant lunch", "kcal": 700, "protein": 40, "carbs": 60, "fat": 30 }
  },
  "removedMeals": { "2026-10-07__ml_cd34ef5": true },
  "aiMeals": {
    "2026-10-07__ml_ab12cd3": [
      { "id": "ai_1", "name": "Banana", "kcal": 105, "protein": 1, "carbs": 27, "fat": 0, "eaten": true, "qty": 1, "unit": "unit", "foodId": "FOOD_ID" }
    ]
  },
  "customMeals": {
    "2026-10-07__cm_1": { "id": "cm_1", "label": "Late snack", "items": [], "logId": "MEAL_LOG_ID" }
  }
}

The client keys everything as <dateKey>__<id>. The parser strips the date prefix with idOf, so on the server each map is keyed by the plain item or meal id.

Key	Value	Meaning
`eaten`	`true` per item id	Plan items the trainee ticked.
`swaps`	food id per item id	The food the trainee swapped in for that day.
`removed`	`true` per item id	Plan items the trainee removed for that day.
`portions`	`{ foodId, qty }` per item id	How much the trainee actually had when it differs from the plan. `qty` is absolute, in the unit `items[].qty` uses. `foodId` is the food shown on that row when the amount was set. The amount counts only while that food is still the one on the row, so a later swap leaves it inert. Quantities above `MAX_PORTION_QTY` (5000) are dropped. Absent on days saved by older app builds.
`mealStatus`	`PLANNED`, `EATEN_OUTSIDE`, `REPLACED` per meal id
`replacement`	`{ name, kcal, protein, carbs, fat, mbp? }` per meal id	What replaced a meal.
`removedMeals`	`true` per meal id	Plan meals the trainee took off the day.
`aiMeals`	array per meal id	Foods added to a plan meal from the AI or search flow. Each has `id`, `name`, macros, `eaten`, and optionally `mbp`, `qty`, `unit` (`gram` or `unit`) and `foodId`.
`customMeals`	`{ id, label, items, logId? }` per id	Meals the trainee composed outside the plan. `logId` links to the `MealLog` row written by the same add flow.

A custom meal with a logId exists in two places: the snapshot holds the day’s arithmetic, and the MealLog row holds the photo and feeds the history tab and the coach’s meal view. Anything that sums a day must count it once, so drop the linked log from the log side.

Today and yesterday are editable in the app. Older days show the saved snapshot read-only.

`MealLog.items` and `FavoriteMeal.items`

logMealBody.items is an array of free-form records, default []. The row-level calories, protein, carbs and fat columns hold the totals, and source is a MealSource:

Value	Meaning
`PLAN`	Logged from a plan meal. The default.
`PHOTO`	From the AI photo analysis.
`FREE_TEXT`	From the AI text analysis.
`MANUAL`	Typed or picked by hand.

The item records are written by the app and by the meal analysis. Do not assume a fixed shape. Read the totals from the columns and treat items as display detail. The analysis output contract is in AI providers.

`DailyMetric.waterLogs`

An array validated by entrySchema in apps/core-api/src/modules/trainee/water-log.ts:

[
  { "id": "REQUEST_OR_RANDOM_ID", "amountMl": 250, "createdAt": "2026-10-07T07:30:00.000Z" },
  { "id": "ANOTHER_ID", "amountMl": -250, "createdAt": "2026-10-07T07:31:00.000Z", "deductEntryId": "REQUEST_OR_RANDOM_ID" }
]

DailyMetric.waterMl is the running total. applyWaterLog makes writes idempotent: a repeated requestId is a no-op, an entry can be deducted only once, and the total can never go below zero.

​Where the contract lives

​Plan shape

​meta

​days[]

​days[].targets

​days[].meals[]

​items[]

​items[].alts[]

​Portions (MBP)

​Alternatives

​Client.foodPreferences

​NutritionDayLog.data

​MealLog.items and FavoriteMeal.items

​DailyMetric.waterLogs

Where the contract lives

Plan shape

`meta`

`days[]`

`days[].targets`

`days[].meals[]`

`items[]`

`items[].alts[]`

Portions (MBP)

Alternatives

`Client.foodPreferences`

`NutritionDayLog.data`

`MealLog.items` and `FavoriteMeal.items`

`DailyMetric.waterLogs`