Training plan JSON

A training plan is stored as one JSON document in Program.content or ProgramTemplate.content when type is TRAINING. There is no Zod schema for it. The contract is a TypeScript type plus a normalizer that accepts anything and returns valid TrainingContent.

Where the contract lives

Repo	File	Role
Backend	`apps/core-api/src/modules/program-templates/training-schema.ts`	Types, `normalizeTrainingContent`, movement helpers, `summarizeTraining`, `stampTechniqueRequest`.
Frontend	`apps/saas/modules/shared/lib/training-schema.ts`	The builder’s mirror of the same types and normalizer, plus factories such as `makeSetRow`.
Frontend	`apps/saas/modules/shared/lib/training-derive.ts`	Derived values for the builder.
Mobile	`src/features/workouts/data/types.ts`	DTO types only. The app does not normalize. It receives plans already normalized and shaped by the trainee endpoints.

The backend and frontend files must change together. A field added in one and not the other is dropped on the next save, because both normalizers rebuild every object from a whitelist of known keys.

Versions

`schemaVersion`	Shape
absent or `1`	The original builder shape: nested supersets, a set count per row, per-day aerobic rows, technique-video triggers without a mode.
`2`	The current shape. `normalizeTrainingContent` always returns `schemaVersion: 2`.

Nothing is migrated in the database. Old content is upgraded each time it is read and is written back as v2 the next time the plan is saved.

What the normalizer migrates

Old shape	Becomes
A row with a nested `superset` object	Two rows. `expandLegacySuperset` creates the partner row with `supersetParentId` pointing at the parent, rest `00:00`, and the parent’s muscle.
`sets: "4"` with no `setRows`	`setRows` with 4 empty working sets, capped at 20.
Per-day `aerobic` rows with durations	`day.cardioMinutes`, summed and rounded from the row durations.
`meta.cardio` (the cardio-only requirement that shipped before daily steps)	`meta.requirement` with `mode: "cardioOnly"`.
No requirement at all, but a day has `cardioMinutes`	`meta.requirement` switched on in `cardioOnly` mode, using the first such day’s minutes.
A technique rule with `firstTime` or `everyN` but no `mode`	`mode: "coachDemand"`. With neither trigger, `mode: "none"`.
Duplicate day ids	`withUniqueDayIds` renames the later duplicates to a free `d<n>`.

Shape

{
  "schemaVersion": 2,
  "meta": {
    "discipline": "mixed",
    "level": "intermediate",
    "split": "upper-lower",
    "workoutsPerWeek": 4,
    "requirement": {
      "on": true,
      "mode": "both",
      "cardio": { "scope": "weekly", "minutes": "120", "activities": ["walking", "cycling"] },
      "steps": { "daily": "8000" }
    },
    "columns": { "tempo": false, "rir": true },
    "autoAlts": true
  },
  "days": [
    {
      "id": "d1",
      "label": "Day A",
      "cardioMinutes": "",
      "stepsDaily": "10000",
      "strength": [
        {
          "id": "s_ab12cd3",
          "exerciseId": "EXERCISE_ID",
          "muscle": "chest",
          "sets": "3",
          "reps": "8",
          "repType": "range",
          "repsHigh": "12",
          "rest": "01:30",
          "weight": "60",
          "rir": "2",
          "tempo": "",
          "notes": "",
          "setRows": [
            { "id": "set_1a2b3c4", "type": "warmup", "reps": "12", "repType": null, "repsHigh": "", "weight": "40", "rest": "", "note": "" },
            { "id": "set_5d6e7f8", "type": "working", "reps": "", "repType": null, "repsHigh": "", "weight": "", "rest": "", "note": "" },
            { "id": "set_9g0h1i2", "type": "drop", "reps": "", "repType": null, "repsHigh": "", "weight": "", "rest": "", "note": "" }
          ],
          "alternatives": ["OTHER_EXERCISE_ID"],
          "supersetParentId": null,
          "techniqueVideo": { "mode": "coachDemand", "firstTime": true, "everyN": "5" }
        }
      ]
    }
  ]
}

Almost every prescription value is a string, including numbers. The builder edits text inputs and the normalizer keeps what the coach typed. Parse at the point of use.

`meta`

Key	Type	Notes
`discipline`	`strength`, `aerobic`, `mixed`	Never trusted from input. `deriveDiscipline` recomputes it: strength rows plus a cardio requirement is `mixed`, cardio only is `aerobic`, otherwise `strength`.
`level`	string	Present only when non-empty.
`split`	string	Present only when non-empty.
`workoutsPerWeek`	number	Clamped to 1 to 7. Default 3.
`requirement`	object	The movement requirement. See below.
`columns`	`{ tempo: boolean, rir: boolean }`	Which optional columns the builder and the app show. Only an explicit `true` turns one on.
`autoAlts`	`true`	Written only when on. When on, the trainee is offered automatic top alternatives on every strength row and the coach’s own `row.alternatives` are not served.
`imported`	`true`	Set by the AI plan import. While true, the normalizer keeps empty values as `''` because an empty string means “missing in the document” and drives the amber markers in the builder.
`source`	string	Human label for the import source.
`draft`	`true`	True until the coach saves from the classic builder.
AutoFit keys	string or number	`autofitTrainingId`, `autofitMenuId`, `autofitTemplateId`, `autofitProgramId`, `autofitWeek`, `autofitNutritionTemplateId`. Carried through verbatim by `pickAutofitMeta`.

Optional keys are absent, not false or '', when they do not apply. That keeps content saved before a feature existed byte-identical after a normalize.

`meta.requirement`

The cardio and daily steps requirement of the plan.

Key	Type	Default
`on`	boolean	`false`
`mode`	`cardioOnly`, `stepsOnly`, `both`, `bothCompensated`	`both`
`cardio.scope`	`perWorkout`, `weekly`	`perWorkout`
`cardio.minutes`	string, positive integer	`"30"`
`cardio.activities`	array of `walking`, `running`, `stairs`, `cycling`	`[]`
`steps.daily`	string, positive integer	`"8000"`

The four modes:

Mode	Cardio counts	Steps count	Either one satisfies the day
`cardioOnly`	yes	no	n/a
`stepsOnly`	no	yes	n/a
`both`	yes	yes	no
`bothCompensated`	yes	yes	yes

Helpers in training-schema.ts answer the questions callers actually ask: requirementHasCardio, requirementHasSteps, requirementCompensates, requirementDailySteps, weeklyCardioMinutes(requirement, workoutsPerWeek), dayCardioMinutes(day, requirement, workoutsPerWeek) and dayStepsGoal(day, requirement). A weekly cardio target is spread across the week’s workouts. dayCardioMinutes returns the target divided by workoutsPerWeek, rounded, unless the day has its own override. The trainee app receives this as a computed movement block, built by apps/core-api/src/modules/trainee/movement.ts from the requirement, the day due today, logged CardioLog minutes and step counts. It reports per-day and weekly targets and totals for cardio and steps, a met flag for each, and todayMet.

`days[]`

Key	Type	Notes
`id`	string	Defaults to `d1`, `d2` and so on. Unique within the plan. `WorkoutLog.dayId`, `CardioLog.dayId` and `TraineeExerciseSubstitution.dayId` reference it.
`label`	string	Defaults to `Day A`, `Day B` and so on.
`strength`	array of rows	The exercises.
`cardioMinutes`	string	Per-day override of the cardio target. Empty means inherit. The normalizer clears it when it equals the plan-level value.
`stepsDaily`	string	Per-day override of the daily steps goal. Same clearing rule.

A plan with no days normalizes to one empty day d1.

`days[].strength[]`

Key	Type	Notes
`id`	string	Row id. Generated as `s_` plus random characters when missing. `TraineeExerciseSubstitution.rowId` references it.
`exerciseId`	string or null	`ExerciseLibraryItem.id`. Null for an unpicked row.
`muscle`	string	Muscle label for the row.
`sets`	string	Always the length of `setRows` when there are any. Defaults to `"3"` for a new row, or `''` on imported content.
`reps`	string	Row-level reps.
`repType`	`fixed`, `range`, `seconds`, `minutes`	How `reps` is read. Unknown values become `fixed`.
`repsHigh`	string	Upper bound, meaningful only for `range`.
`rest`	string	Rest as `mm:ss`.
`weight`	string
`rir`	string	Reps in reserve. Shown only when `meta.columns.rir` is on.
`tempo`	string	Shown only when `meta.columns.tempo` is on.
`notes`	string
`setRows`	array	Per-set breakdown. See below.
`alternatives`	string array	Exercise ids the coach approved as substitutes. Deduplicated.
`supersetParentId`	string or null	Set on the partner row of a superset. Points at the parent row’s `id`.
`techniqueVideo`	object	Technique video rule. See below.

Supersets

A superset is two linked rows, not a nested object. The partner row carries supersetParentId. The rest between the two exercises is SUPERSET_REST (00:00), and the pair shares the parent’s rest after the round. The builder shows the partner’s rest as a read-only mirror of the parent’s. The mobile app pairs rows in src/features/workouts/lib/supersets.ts.

`setRows[]`

Key	Type	Notes
`id`	string	Generated as `set_` plus random characters when missing.
`type`	`warmup`, `working`, `drop`	Unknown values become `working`.
`reps`	string	Empty means inherit the row’s `reps`.
`repType`	rep type or null	Null inherits the row’s `repType`.
`repsHigh`	string
`weight`	string
`rest`	string
`note`	string

`techniqueVideo`

Controls whether the trainee is asked to film this exercise.

Key	Type	Notes
`mode`	`none`, `free`, `coachDemand`	`none` and `free` carry no requirement. `coachDemand` makes filming a requirement driven by the triggers below. A `requestedAt` stamp reaches the trainee as a demand whatever the mode.
`firstTime`	boolean	Ask the first time the trainee performs the exercise.
`everyN`	string	Ask every N workouts. A positive integer as a string, or `''`.
`requestedAt`	ISO timestamp	Optional. A coach’s one-shot “film this in the next workout”, written from the check-in review screen by `stampTechniqueRequest`. It stays on the row and stops counting once the trainee uploads a newer video of that exercise. The key is absent, never null or `''`, when there is no valid stamp.

techniqueVideoRequired(rule) is true when mode is coachDemand and at least one trigger is set. The request quota shown to the trainee is derived in apps/core-api/src/modules/trainee/technique-prompts.ts from these rules and the trainee’s TechniqueVideo rows. Nothing is stored for it. stampTechniqueRequest(raw, exerciseId, requestedAt) rewrites the stored shape, not normalized content. It touches only the technique rule of rows that prescribe that exercise, including a v1 nested superset partner, and returns how many rows it stamped.

What is not in the JSON

Data	Where it lives
Exercise names, videos, muscles	`ExerciseLibraryItem`, merged with `ExerciseStudioOverride`. The plan stores only ids.
A trainee’s saved substitution for a row	`TraineeExerciseSubstitution`. Anything stored inside `content` would be erased by the coach’s next save.
What the trainee actually did	`WorkoutLog.entries`. See Tracking.
A PDF or link plan	`Program.pdfUrl`, with `content` left as `{}`. See Programs and templates.

Summary helper

summarizeTraining(raw) normalizes and returns discipline, dayCount, exerciseCount and workoutsPerWeek, plus imported and draft flags when set. List endpoints use it so they do not ship whole plans.

​Where the contract lives

​Versions

​What the normalizer migrates

​Shape

​meta

​meta.requirement

​days[]

​days[].strength[]

​Supersets

​setRows[]

​techniqueVideo

​What is not in the JSON

​Summary helper