Tracking models

Tracking tables are client scoped. None of them has a studioId. They all cascade from Client, and any query must first establish that the client belongs to the caller’s studio. Trainee “days” follow the trainee device’s time zone (Client.timezone), not the studio’s. @db.Date columns hold the civil day. Timestamp columns hold instants.

`WorkoutLog`

Table workout_logs. One recorded workout session.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`programId`	`String?`	The program it was performed from. The relation has no `onDelete` rule, so it defaults to restricting a program delete while logs point at it.
`performedOn`	`DateTime`	When the workout happened.
`label`	`String?`	Workout name snapshot.
`dayId`	`String?`	The training day id inside the program content.
`note`	`String?`
`entries`	`Json`	What was performed. See below.
`durationSec`	`Int?`
`completed`	`Boolean`	Default `false`.
`createdAt`	`DateTime`

Indexes: clientId, programId, (clientId, performedOn), (clientId, completed, performedOn).

`entries`

logWorkoutBody.entries accepts an array of free-form records. The app writes this shape from mobile/src/features/workouts/presentation/WorkoutDayScreen.tsx:

[
  {
    "exerciseId": "EXERCISE_ID",
    "name": "Bench press",
    "done": true,
    "tempo": null,
    "sets": [
      { "setNumber": 1, "reps": 10, "targetReps": 10, "weight": 60, "rir": "2", "rm": null, "done": true },
      { "setNumber": 2, "reps": null, "targetReps": 10, "weight": null, "rir": null, "rm": null, "done": false }
    ]
  }
]

Rules worth knowing:

A set the trainee never performed keeps its entry and done: false, with reps and weight as null. Targets and placeholders are never written as if performed.
A performed set with no weight logs weight: null. That is also how a bodyweight set is logged.
rir is a string and is null when the trainee did not touch it.

readWorkoutLog(entries) in apps/core-api/src/modules/trainee/workout-log-view.ts is the tolerant reader. It skips non-objects, coerces numeric strings, counts a set as performed when done is true or, on older logs with no done flag, when it has reps or weight, and computes setCount and volumeKg (weight times reps over performed sets).

`CardioLog`

Table cardio_logs. A single aerobic session the trainee timed in the app or added by hand.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`activity`	`String`	`walking`, `running`, `stairs`, `cycling` or `other` (`cardioActivity` in `trainee.schema.ts`).
`minutes`	`Int`	Capped at `MAX_CARDIO_MINUTES`, 600.
`performedOn`	`DateTime` (`@db.Date`)	The civil day.
`startedAt`	`DateTime`
`source`	`CardioLogSource`	`WORKOUT` (timed during a workout) or `MANUAL`. Default `MANUAL`.
`programId`, `dayId`	`String?`	Program attribution as plain ids. No foreign key on purpose: deleting a program must never take the trainee’s activity history with it.
`createdAt`	`DateTime`

Index: (clientId, performedOn).

`DailyMetric`

Table daily_metrics. One row per trainee per day.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`date`	`DateTime` (`@db.Date`)
`weightKg`	`Float?`
`waterMl`	`Int?`	Running total for the day.
`waterLogs`	`Json?`	Per-entry history. Shape in Nutrition plan JSON.
`steps`	`Int?`	Capped at `MAX_DAILY_STEPS`, 100000.
`restingHeartRate`, `avgHeartRate`	`Int?`
`measurements`	`Json?`	Body circumferences. See below.
`notes`	`String?`
`createdAt`, `updatedAt`	`DateTime`

Unique on (clientId, date). Index on clientId.

`measurements`

Keys accepted by logMeasurementsBody: chest, waist, hips, arm, thigh, neck. Each is a positive number up to 500. At least one is required per write. A form’s body measurement field merges into the same object on submit.

{ "waist": 82.5, "hips": 97, "chest": 101 }

`HealthSample`

Table health_samples. Raw samples from Apple Health or Health Connect, from the first version of the health sync.

Nothing writes to this table any more. The app now sends one step total per day, which is stored in DailyMetric.steps. The old endpoint POST /v1/trainee/health/samples still answers so older app builds do not fail, but it stores nothing. The only code that touches this table is the trainee account deletion, which clears it.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`type`	`HealthMetricType`	`STEPS` or `HEART_RATE`.
`value`	`Float`
`unit`	`String`
`source`	`HealthSource`	`HEALTHKIT` or `HEALTH_CONNECT`.
`externalId`	`String`	The sample id on the device.
`startedAt`, `endedAt`	`DateTime`
`createdAt`	`DateTime`

Unique on (clientId, type, source, externalId). Index on (clientId, type, startedAt). The current sync is covered in Apple Health and Health Connect.

`WeightEntry`

Table weight_entries. Dedicated weigh-in history, separate from DailyMetric. It allows several entries per day and powers the weight view on the client card.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`weightKg`	`Float`	Positive, up to 500.
`recordedAt`	`DateTime`	Default `now()`.
`source`	`String?`	Where it came from, for example `form` for a weight captured by a form submission.
`formResponseId`	`String?`	The response that produced it, when `source` is a form. Plain id.
`note`	`String?`	Up to 200 characters.
`createdAt`	`DateTime`

Indexes: clientId, (clientId, recordedAt).

`ClientAppDay`

Table client_app_days. One row per day the trainee opened the app.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`date`	`DateTime` (`@db.Date`)
`platform`	`String?`	`ios` or `android`.
`createdAt`	`DateTime`

Unique on (clientId, date). Client.lastCheckInAt only keeps the latest open, so “opened the app but logged nothing” needs this history.

`ClientPhoto`

Table client_photos. The trainee’s progress photo gallery.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`url`	`String`
`takenAt`	`DateTime`	Default `now()`.
`source`	`String?`	Where the photo came from. Photos arrive from the app and from form image fields flagged to save to the client card.
`pose`	`String?`	`FRONT`, `SIDE` or `BACK`, validated in code. Used to pair before and after photos.
`formResponseId`	`String?`	The response that produced it. Plain id.
`createdAt`	`DateTime`

Indexes: clientId, (clientId, takenAt).

`MealLog`

Table meal_logs. One logged meal.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`consumedAt`	`DateTime`
`source`	`MealSource`	`PLAN`, `PHOTO`, `FREE_TEXT`, `MANUAL`. Default `PLAN`.
`name`	`String?`	Up to 120 characters.
`note`	`String?`
`items`	`Json`	Free-form item records.
`calories`, `protein`, `carbs`, `fat`	`Float?`	Totals.
`photoUrl`	`String?`
`createdAt`	`DateTime`

Indexes: clientId, (clientId, consumedAt).

`NutritionDayLog`

Table nutrition_day_logs. The app’s snapshot of one nutrition day.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`date`	`DateTime` (`@db.Date`)
`data`	`Json`	The day snapshot. Shape in Nutrition plan JSON.
`createdAt`, `updatedAt`	`DateTime`

Unique on (clientId, date).

`FavoriteMeal`

Table favorite_meals. A meal the trainee saved to log again. Same columns as MealLog minus consumedAt: name (required), source (default MANUAL), note, items (nullable), the four macro totals and photoUrl. Index on clientId.

`TechniqueVideo`

Table technique_videos. A video the trainee filmed for coach review.

Field	Type	Meaning
`clientId`	`String`	Cascade delete.
`exerciseId`	`String?`	The exercise filmed. Plain id.
`url`	`String`
`thumbnailUrl`	`String?`
`status`	`TechniqueVideoStatus`	Default `PENDING`.
`coachNote`	`String?`	Written feedback.
`voiceNoteUrl`	`String?`	Recorded feedback.
`reviewedById`	`String?`	The reviewing coach.
`reviewedAt`	`DateTime?`
`feedbackSeenAt`	`DateTime?`	When the trainee opened the feedback.
`createdAt`	`DateTime`

Indexes: clientId, status, (clientId, exerciseId), (clientId, createdAt).

`TechniqueVideoStatus`

Value	Meaning
`PENDING`	Uploaded, waiting for a coach.
`IN_REVIEW`	A review is in progress. The status is set through the technique videos update endpoint.
`REVIEWED`	Feedback was sent.

Which exercises ask for a video is configured in the training plan. See Training plan JSON.

Derived values that are not stored

Personal records, last set history and the workout time estimate are computed from WorkoutLog.entries on read.
The movement summary (cardio and steps progress) is computed from CardioLog, DailyMetric.steps and the plan requirement.
The water goal comes from the nutrition plan day’s targets.water.

​WorkoutLog

​entries

​CardioLog

​DailyMetric

​measurements

​HealthSample

​WeightEntry

​ClientAppDay

​ClientPhoto

​MealLog

​NutritionDayLog

​FavoriteMeal

​TechniqueVideo

​TechniqueVideoStatus

​Derived values that are not stored

`WorkoutLog`

`entries`

`CardioLog`

`DailyMetric`

`measurements`

`HealthSample`

`WeightEntry`

`ClientAppDay`

`ClientPhoto`

`MealLog`

`NutritionDayLog`

`FavoriteMeal`

`TechniqueVideo`

`TechniqueVideoStatus`

Derived values that are not stored