Tracking

The tracking module returns raw tracking rows for one trainee. It is read-only. The trainee app writes these rows through the trainee lane, and the richer computed views (adherence, personal records, weekly averages) live in Client tracking and Check-ins.


Source	`backend/apps/core-api/src/modules/tracking/`
Lane	Web gateway only
Base path	`/v1/web/tracking`
Guards	Service auth plus web user context. No `requireRole` guard, so every studio role can call it.

The module follows the five-file pattern: tracking.routes.ts, tracking.controller.ts, tracking.service.ts, tracking.repository.ts, tracking.schema.ts.

Shared behaviour

All three endpoints parse the query with the same Zod schema, trackingListQuery, and run the same steps:

The controller reads req.auth.studioId. A missing value throws UNAUTHORIZED.
The service calls repo.clientInStudio(studioId, clientId). If the trainee is not in the caller’s studio it throws NOT_FOUND with the message client not found.
The repository runs a findMany and a count in parallel with the same where, and returns items and total.

The tenancy check is on the trainee only. The module does not apply coach permission scoping from middleware/coach-access.ts, so a coach restricted to assigned trainees can still read any trainee in the studio through these routes.

Query parameters

string

required

The trainee id. Minimum length 1.

date

Lower bound, inclusive. Parsed with z.coerce.date(), so an ISO date or datetime string works.

date

Upper bound, inclusive. Parsed with z.coerce.date().

integer

default:"1"

Page number, positive.

integer

default:"20"

Rows per page. Positive, maximum 500.

Response envelope

Every endpoint returns the same wrapper inside data:

{
  "ok": true,
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_01HZX4"
}

items are full Prisma rows with no field selection, so every column of the model is returned.

Errors

Code	Status	When
`UNAUTHORIZED`	401	No studio on the request context.
`NOT_FOUND`	404	`clientId` does not belong to the caller’s studio.
`VALIDATION`	422	Query fails `trackingListQuery`, for example a missing `clientId` or `pageSize` above 500.

Endpoints

`GET /v1/web/tracking/daily-metrics`

Lists DailyMetric rows for a trainee, newest date first. Auth: web lane, any role. from and to filter on date, a @db.Date column with one row per trainee per day (@@unique([clientId, date])). Rows are ordered by date descending. Response: data.items is an array of DailyMetric rows.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf2k9x1a0001qz8h3v7d2m4p",
        "clientId": "cmf1a7b2c0003qz8h9k1l2m3n",
        "date": "2026-10-05T00:00:00.000Z",
        "weightKg": 78.4,
        "waterMl": 2250,
        "waterLogs": [{ "ml": 500, "at": "2026-10-05T06:12:00.000Z" }],
        "steps": 9120,
        "restingHeartRate": 58,
        "avgHeartRate": 71,
        "measurements": { "waist": 84.5 },
        "notes": null,
        "createdAt": "2026-10-05T06:12:03.000Z",
        "updatedAt": "2026-10-05T18:40:11.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20
  }
}

waterLogs and measurements are Json columns. Their inner shape is written by the trainee module, not by this one, so the example values above are illustrative only.

`GET /v1/web/tracking/meal-logs`

Lists MealLog rows for a trainee, newest first. Auth: web lane, any role. from and to filter on consumedAt. Rows are ordered by consumedAt descending. Response: data.items is an array of MealLog rows.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf2kb0qj0007qz8h5t6u7v8w",
        "clientId": "cmf1a7b2c0003qz8h9k1l2m3n",
        "consumedAt": "2026-10-05T10:30:00.000Z",
        "source": "PLAN",
        "name": "Lunch",
        "note": null,
        "items": [],
        "calories": 640,
        "protein": 48,
        "carbs": 62,
        "fat": 19,
        "photoUrl": null,
        "createdAt": "2026-10-05T10:31:44.000Z"
      }
    ],
    "total": 118,
    "page": 1,
    "pageSize": 20
  }
}

source is the Prisma MealSource enum and defaults to PLAN. items is a required Json column holding the logged foods. Its inner shape is owned by the trainee module.

`GET /v1/web/tracking/workout-logs`

Lists WorkoutLog rows for a trainee, newest first. Auth: web lane, any role. from and to filter on performedOn. Rows are ordered by performedOn descending. Both completed and unfinished logs are returned. There is no filter on completed. Response: data.items is an array of WorkoutLog rows.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf2kc4tn000bqz8h1a2b3c4d",
        "clientId": "cmf1a7b2c0003qz8h9k1l2m3n",
        "programId": "cmf0z3y4x0002qz8h7g8h9i0j",
        "performedOn": "2026-10-04T16:05:00.000Z",
        "label": "A",
        "dayId": "day_1",
        "note": null,
        "entries": [],
        "durationSec": 3180,
        "completed": true,
        "createdAt": "2026-10-04T17:00:12.000Z"
      }
    ],
    "total": 27,
    "page": 1,
    "pageSize": 20
  }
}

entries is a required Json column holding the logged exercises and sets. Its inner shape is owned by the trainee module.

API basics

Trainees

Plans and libraries

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Tracking

Shared behaviour

Query parameters

Response envelope

Errors

Endpoints

`GET /v1/web/tracking/daily-metrics`

`GET /v1/web/tracking/meal-logs`

`GET /v1/web/tracking/workout-logs`

​Shared behaviour

​Query parameters

​Response envelope

​Errors

​Endpoints

​GET /v1/web/tracking/daily-metrics

​GET /v1/web/tracking/meal-logs

​GET /v1/web/tracking/workout-logs

Shared behaviour

Query parameters

Response envelope

Errors

Endpoints

`GET /v1/web/tracking/daily-metrics`

`GET /v1/web/tracking/meal-logs`

`GET /v1/web/tracking/workout-logs`