Check-ins

A check-in is a filled intake form or a filled recurring check-in form waiting for a coach to review it. This module is the review surface in the coach web app. It was built in three layers, which the code calls waves:

The queue. List filled forms, open one, write feedback, save a draft, reassign, remind.
Tracking. A per-trainee timeline of nutrition, workouts, steps, cardio, weigh-ins and forms, shown beside the form.
Insights. Deterministic status per area, flags on the queue rows, and a suggested feedback message.


Source	`backend/apps/core-api/src/modules/checkins/`
Lane	Web gateway only
Base path	`/v1/web/checkins`
Guards	Service auth plus web user context, then the scope rules below

Files:

File	Purpose
`checkins.service.ts`	Queue, detail, feedback, draft, reassign, remind, remove
`checkins-tracking.ts`	The tracking timeline and the technique video request
`checkins-insights.ts`	Containers, flags, overall verdict, suggested message, caches
`checkins-scope.ts`	Who sees which trainees
`checkins-queue.ts`	What the queue hides
`checkins.schema.ts`	Request schemas and the wire types the panel builds against
`checkins.repository.ts`	All Prisma access

Data model

The queue is made of FormResponse rows whose template type is INTAKE or CHECK_IN. One-time forms and documents to sign never enter this surface. The response id is the one id the whole surface keys on. Everything the review adds lives in CheckinReview, keyed by a unique responseId:

Field	Meaning
`assignedCoachId`	An admin routed this one form to another coach
`draft`	Autosaved, unfinished feedback (JSON)
`note`	Internal write-up. Never sent to the trainee
`message`, `channels`, `attachedChanges`	What was sent to the trainee
`handledById`, `handledByName`, `handledAt`	Completion stamp
`remindedAt`	Last “feedback is on its way” nudge
`dismissedAt`	Taken off the queue

A response with no review row, or with no handledAt, is pending. When a review is completed, the handled stamp is mirrored onto the FormResponse (handledAt, handledById, handledByName, handledNote) so the inbox reads the same truth. In the API, INTAKE is called onboarding and CHECK_IN is called update.

Auth and scope

Every handler builds the caller with callerOf(req):

No studio or user on the request: UNAUTHORIZED.
Role TRAINEE: FORBIDDEN (coaches only).

The service then resolves a scope from the caller’s Coach row (resolveScope):

Term	Rule
Dismissed	A coach row with `active: false` is refused with `FORBIDDEN` (`this team member has been removed`), unless the caller is the owner
`isAdmin`	Role `OWNER`, or a coach row with role `HEAD_COACH`
`seesAllTrainees`	Role `OWNER` or `HEAD_COACH`, or a coach row with role `HEAD_COACH`, or stored permissions with `trainees: "all"` (`seesAllCheckinTrainees`)

A caller who does not see all trainees sees a form only when the trainee is assigned to them, as lead coach (Client.coachId) or through ClientCoach, or when an admin routed that specific form to them. A caller with no coach row and no all-access sees nothing. A form outside the caller’s scope answers NOT_FOUND (check-in not found), the same as an id from another studio, so the API never reveals which ids exist. The trainee-level routes apply the same rule to a trainee and answer NOT_FOUND (trainee not found).

What the queue hides

checkins-queue.ts filters two kinds of responses out of the queue and its counts, without deleting anything:

A form a coach took off the queue (CheckinReview.dismissedAt set).
Form history imported from AutoFit. Those answers carry a marker key (ANSWER_ID_KEY from the AutoFit import).

Both stay everywhere else: the trainee’s form history, the tracking timeline and the “update number N” ordinals still count them.

Queue endpoints

`GET /v1/web/checkins`

The review queue with its quick stats. Auth: web lane, any coach role, scoped.

string

default:"pending"

pending, handled or all.

string

default:"all"

all, update or onboarding.

string

Comma-separated coach ids. Honoured for admins only, ignored for everyone else. Matches the row’s effective coach.

string

ISO date or datetime. Only the calendar day is used. Keeps rows whose form was sent on or after that day (UTC day start). Rows with no send time are dropped.

string

Same format. Inclusive, up to the end of that UTC day.

string

Same format, on the fill time.

string

Same format, on the fill time.

string

Trimmed, minimum length 1. Case-insensitive contains on the trainee name.

string

default:"wait_desc"

wait_desc or wait_asc. Wait is the time from fill to handled, or from fill to now while pending.

There is no pagination. The service loads every in-scope response for the type and search, builds rows, then filters and sorts in memory. How a row is built:

coach is the admin reroute when there is one, otherwise the trainee’s lead coach, otherwise null.
n is the trainee’s Nth update, 1-based, ranked by fill time across all of their check-ins. Onboarding is always 1.
sentAt is when the form assignment was created. filledAt is submittedAt, falling back to createdAt.
flags holds flag keys, see Flags. Pending rows get freshly computed flags (batched, cached six hours). Handled rows only show flags that are already cached. If the flag engine fails, the queue is served without flags.

counts describes the whole queue in view (scope, type and search). It deliberately ignores the status, coachIds and date filters, so the numbers do not jump as the coach switches tabs. Response:

{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "cmresp00010qz8h1a2b3c4d",
        "trainee": { "id": "cmf1a7b2c0003qz8h9k1l2m3n", "name": "Dana Levi", "joinedAt": "2026-07-01T00:00:00.000Z" },
        "coach": { "id": "cmcoach00010qz8h1a2b3c4d", "name": "Noa" },
        "type": "update",
        "n": 6,
        "sentAt": "2026-10-03T05:00:00.000Z",
        "filledAt": "2026-10-03T18:22:00.000Z",
        "handledAt": null,
        "handledByName": null,
        "flags": ["adh"]
      }
    ],
    "counts": {
      "pending": 14,
      "handled": 212,
      "all": 226,
      "newTrainees": 2,
      "over48h": 3,
      "onboardingPending": 2,
      "flagged": 4
    },
    "isAdmin": true,
    "seesAllTrainees": true,
    "coaches": [
      { "id": "cmcoach00010qz8h1a2b3c4d", "name": "Noa" },
      { "id": "cmcoach00020qz8h5e6f7g8h", "name": "Omer" }
    ]
  }
}

over48h counts pending rows filled at least 48 hours ago.
newTrainees and onboardingPending are computed the same way: pending onboarding rows.
flagged counts pending rows with at least one flag.
coaches lists the studio’s active coaches for the filter dropdown. It is empty unless the caller sees all trainees.

Errors: UNAUTHORIZED, FORBIDDEN, VALIDATION (422) for a bad query, such as a date that is not a real calendar day.

`POST /v1/web/checkins/bulk-delete`

Takes forms off the queue. Despite the path, it deletes no form. Auth: web lane, any coach role, scoped.

string[]

required

Between 1 and 200 response ids. Duplicates are removed.

Only in-scope intake and check-in responses of the studio are affected. Ids outside the caller’s scope are skipped silently. In one transaction the service:

Sets dismissedAt on each form’s CheckinReview, creating the row when there is none.
Deletes the inbox task items linked to those forms (InboxItem rows whose autoKey matches the queue task prefixes for that response).

It then writes one AuditLog row per form with action checkin.dismissed and resource type CHECKIN_REVIEW. The trainee’s filled forms, their reviews, weigh-ins and photos are all kept. The path name is the web app’s existing contract. A comment in the service notes that a real delete here once wiped hundreds of forms. Response:

{
  "ok": true,
  "data": { "deleted": 12 }
}

deleted is the number of forms taken off the queue. It can be lower than the number of ids sent. Errors: VALIDATION for an empty list or more than 200 ids. UNAUTHORIZED, FORBIDDEN.

`GET /v1/web/checkins/:id`

One check-in in full: the form, the answers, the previous answers for comparison, the trainee, the draft, and plan changes. Auth: web lane, any coach role, scoped.

string

required

The FormResponse id.

What the service assembles:

form.pages from the response’s schemaSnapshot, falling back to the template’s current schema. Display-only field types are skipped and empty pages are dropped.
previousAnswers and previousFilledAt: the trainee’s previous check-in, for updates only. null on onboarding.
planChangesSince: the trainee’s TRAINING and NUTRITION programs that are not drafts and were updated after this form was filled. A plan held from an intake review appears here too, with its release state.
sessionPrograms: onboarding only. The plans assigned from this review in hold mode (Program.releaseResponseId equals this response), oldest first, in any status. The pending ones are what the release route sends, see Programs.
flags: full flag objects for the trainee.
suggestedMessage: a prefilled feedback text, only while the draft holds no trainee message. A coach’s own words always win. An autosaved internal note alone does not block the suggestion.

If the insights engine fails, flags is empty and suggestedMessage is null. The detail itself still loads. Response:

{
  "ok": true,
  "data": {
    "form": {
      "title": "Weekly check-in",
      "type": "update",
      "n": 6,
      "filledAt": "2026-10-03T18:22:00.000Z",
      "sentAt": "2026-10-03T05:00:00.000Z",
      "pages": [
        {
          "title": null,
          "questions": [
            { "key": "weight", "label": "Weight this morning", "type": "number", "unit": "kg" },
            {
              "key": "energy",
              "label": "Energy this week",
              "type": "select",
              "options": [
                { "value": "low", "label": "Low" },
                { "value": "high", "label": "High" }
              ]
            }
          ]
        }
      ]
    },
    "answers": { "weight": 78.4, "energy": "high" },
    "previousAnswers": { "weight": 78.9, "energy": "low" },
    "previousFilledAt": "2026-09-26T17:40:00.000Z",
    "trainee": {
      "id": "cmf1a7b2c0003qz8h9k1l2m3n",
      "name": "Dana Levi",
      "phone": "+972 500000000",
      "joinedAt": "2026-07-01T00:00:00.000Z",
      "coachName": "Noa",
      "subscriptionEndsOn": "2026-12-31T00:00:00.000Z",
      "goalWeightKg": 75
    },
    "handled": null,
    "draft": {
      "note": "",
      "sendToTrainee": true,
      "message": "",
      "channels": ["push"],
      "attachedChangeIds": []
    },
    "planChangesSince": [
      {
        "id": "cmf7p1q2r0001qz8h3s4t5u6v",
        "type": "TRAINING",
        "name": "Push pull legs",
        "updatedAt": "2026-10-04T08:10:00.000Z",
        "releasePending": false,
        "releaseAt": null
      }
    ],
    "sessionPrograms": [],
    "flags": [{ "key": "adh", "label": "...", "detail": "..." }],
    "suggestedMessage": "..."
  }
}

Field types and question keys in the example are illustrative. label, detail and suggestedMessage are Hebrew strings. handled is { "at": "...", "byName": "..." } once the review is complete. draft is null when nothing was saved. Errors: NOT_FOUND (check-in not found), FORBIDDEN, UNAUTHORIZED.

`POST /v1/web/checkins/:id/feedback`

Completes a review. It records an internal note, a message to the trainee, or both, and marks the form handled. Auth: web lane, any coach role, scoped.

string

required

The FormResponse id.

string

default:""

Internal write-up. Trimmed, maximum 4000 characters. Never sent to the trainee.

boolean

default:"false"

Whether a message goes to the trainee. When the key is missing, it is inferred: true if message is not blank or channels is not empty. This keeps older web clients working.

string

default:""

Text for the trainee. Maximum 4000 characters.

string[]

default:"[]"

Up to two of push and whatsapp.

string[]

default:"[]"

Up to 20 program ids to mention in the message.

Rules, enforced by the schema and again in the service:

With sendToTrainee: true, a non-blank message and at least one channel are required.
With sendToTrainee: false, a non-blank note is required.

What happens, in order:

Attached plans. Ids are resolved strictly inside this trainee. Ids that do not belong are dropped silently. For each resolved plan, a line naming the plan and pointing to the app is appended to the message.
Push, when chosen: notifier.send with type TRAINER_MESSAGE and the message as a literal body.
WhatsApp, when chosen: sent through SmartSend with the studio’s own API key from Studio.settings.smartsend.apiKey.
Review. CheckinReview is upserted with the note, message, channels, attached plans and the handled stamp. The draft is cleared.
Mirror. The handled stamp is copied onto the FormResponse. handledNote is the internal note when there is one, otherwise the trainee message.
Audit. An AuditLog row with action checkin.feedback.sent.
Activity. A ClientActivity row with type CHECKIN_FEEDBACK_SENT, entity type CHECKIN, the form name, and metadata sentToTrainee and channels. It is written whether or not anything went to the trainee.
Automation. formFeedbackSentHook fires the FORM_FEEDBACK_SENT task automations and flow runs for the form. A failure there is logged and does not fail the request.

A failed or skipped channel does not stop the review from being marked handled. The response says what each channel did. Response:

{
  "ok": true,
  "data": {
    "ok": true,
    "handledAt": "2026-10-06T09:30:00.000Z",
    "channelResults": { "push": "sent", "whatsapp": "not_connected" }
  }
}

channelResults has one key per channel requested:

Value	Meaning
`sent`	Delivered to the provider
`disabled`	Push only. The studio has the `TRAINER_MESSAGE` notification type switched off
`no_devices`	Push only. The trainee has no registered device
`not_connected`	WhatsApp only. The studio has no SmartSend key
`no_phone`	WhatsApp only. The trainee has no phone number
`failed`	WhatsApp only. The send threw. Logged as a warning

Errors: VALIDATION (422) for the schema rules, with Hebrew messages on message, channels or note. BAD_REQUEST for the same three rules from the service guard. NOT_FOUND (check-in not found). FORBIDDEN, UNAUTHORIZED.

`PUT /v1/web/checkins/:id/draft`

Autosaves unfinished feedback. Auth: web lane, any coach role, scoped.

string

required

The FormResponse id.

The body has the same five fields as feedback: note, sendToTrainee, message, channels, attachedChangeIds, with the same defaults and limits. Only the shape is checked. A draft may have an empty message, no channel and no note, so autosave never bounces. note is not trimmed here. If the review is already handled, the route returns success and writes nothing. An autosave that lands just after the send must not bring stale text back. Response:

{
  "ok": true,
  "data": { "ok": true }
}

Errors: NOT_FOUND (check-in not found), VALIDATION, FORBIDDEN, UNAUTHORIZED.

`POST /v1/web/checkins/:id/reassign`

Routes one form to another coach. The trainee’s own coach assignment does not change. Auth: web lane, admins only (isAdmin).

string

required

The FormResponse id.

string

required

The Coach row id of an active coach in the studio.

Sets CheckinReview.assignedCoachId. From then on that coach sees this form in their queue and can open the trainee’s tracking and insights, even when the trainee is not assigned to them. An AuditLog row with action checkin.reassigned is written. No notification is sent to the new coach by this route. Response:

{
  "ok": true,
  "data": { "ok": true }
}

Errors: FORBIDDEN (admins only). NOT_FOUND (check-in not found). BAD_REQUEST (assignee is not an active coach here).

`POST /v1/web/checkins/:id/remind`

Sends the trainee a short push saying the coach is still going over their update. Auth: web lane, any coach role, scoped.

string

required

The FormResponse id.

No body. Sends a TRAINER_MESSAGE push with a fixed Hebrew sentence that addresses the trainee by first name, then stamps CheckinReview.remindedAt. There is no rate limit or cooldown in the service, and the result of the push is not reported back. Response:

{
  "ok": true,
  "data": { "ok": true }
}

Errors: NOT_FOUND (check-in not found), FORBIDDEN, UNAUTHORIZED.

Trainee endpoints

These three routes are keyed by trainee, not by form. They are registered before /:id so the literal trainee segment is never read as a response id.

`GET /v1/web/checkins/trainee/:clientId/tracking`

The per-trainee timeline for a date range. Auth: web lane, any coach role, scoped to the trainee.

string

required

The trainee id.

string

required

ISO date or datetime. Only the calendar day is used.

string

required

Same format. Inclusive.

The range must be between 1 and 92 days (TRACKING_MAX_DAYS). Days are civil days in the studio’s time zone (Studio.timezone, default Asia/Jerusalem). Note that this differs from Client tracking, which prefers the trainee’s own time zone. The payload has two kinds of data. Range data, which depends on from and to:

days: one entry per day in the range.
- nutrition is null for an empty day: no plan meals, no snapshot, nothing logged and no water. Otherwise it carries consumed and target from the partner module’s nutritionDays (the same source client tracking reads, fetched in 62 day chunks), meal counts, the number of swaps, water, and one slot per plan meal.
- A slot’s eaten is null when the trainee never opened that day, so eaten-ness is unknown. It is true when the meal was eaten outside, replaced, or has an eaten item.
- swapped counts item swaps plus whole-meal replacements.
- workout shows one session per day. A completed session outranks a partial one. Abandoned starts are not sessions. splitLetter is the letter (A, B, C) of the plan day, resolved from the program the log itself was recorded against, so old logs keep their letter after a plan change. done is true for completed, false for partial, null for no session.
- steps.source is always manual. DailyMetric has no provenance column, so the service cannot tell device data from typed data.
- sleep is always null. There is no sleep data model.
weighIns: weigh-ins inside the range. deltaKg is against the previous weigh-in ever, not the previous one in range. measurements is the numeric DailyMetric.measurements of that day, and photos are the ClientPhoto rows taken that day.
sessions: every session in the range with its exercises. reps is the done-set reps joined with slashes. volume is weight times reps over weighted sets.
planChanges: programs updated inside the range.
forms: the trainee’s filled forms in the range, oldest first, with their update number.

Snapshots, which do not depend on the range. The panel fetches the timeline in window chunks, and every chunk carries the same values:

targets: today’s nutrition target (in portions when the studio uses portions, with kcal then holding the sum of the three portion values), workouts per week, weekly cardio minutes, steps goal, goal weight and water goal, plus trainingFilePlan and nutritionFilePlan. For a file plan the related targets are null.
splitDays: every day of every active training plan as the coach prescribed it, with no trainee swaps. Exercise names use the studio’s override when it renamed a shared exercise.
latestTechniqueVideos: keyed by exercise id, the newest technique video of that exercise in any status.
techniqueRequests: keyed by exercise id, the timestamp of an open coach request. A request is open while no technique video of that exercise was uploaded at or after it.

Response:

{
  "ok": true,
  "data": {
    "days": [
      {
        "date": "2026-10-05",
        "nutrition": {
          "mode": "grams",
          "consumed": { "kcal": 1760, "protein": 142, "carbs": 168, "fat": 51 },
          "target": { "kcal": 1800, "protein": 150, "carbs": 160, "fat": 55 },
          "mealsEaten": 3,
          "mealsTotal": 4,
          "swapped": 1,
          "waterMl": 2250,
          "slots": [
            { "key": "ml_p9q8r7s", "label": "Breakfast", "eaten": true },
            { "key": "ml_t6u5v4w", "label": "Lunch", "eaten": false }
          ]
        },
        "workout": { "plannedLabel": "Day A", "splitLetter": "A", "done": true, "logId": "cmf2kc4tn000bqz8h1a2b3c4d" },
        "steps": { "count": 9120, "source": "manual" },
        "cardioMin": 30,
        "sleep": null
      }
    ],
    "weighIns": [
      {
        "date": "2026-10-05",
        "weightKg": 78.4,
        "deltaKg": -0.5,
        "measurements": { "waist": 84.5 },
        "photos": [{ "url": "https://media.example.com/photos/cmph0001.jpg", "pose": "front" }]
      }
    ],
    "sessions": [
      {
        "logId": "cmf2kc4tn000bqz8h1a2b3c4d",
        "performedOn": "2026-10-05T16:05:00.000Z",
        "label": "A",
        "exercises": [
          { "exerciseId": "cmexr8s9t0004qz8h2u3v4w5x", "name": "Bench press", "topWeight": 82.5, "sets": 3, "reps": "8/8/6", "volume": 1775 }
        ],
        "durationSec": 3180,
        "steps": 9120,
        "cardioMin": 30
      }
    ],
    "planChanges": [
      { "id": "cmf7p1q2r0001qz8h3s4t5u6v", "type": "TRAINING", "name": "Push pull legs", "updatedAt": "2026-10-04T08:10:00.000Z" }
    ],
    "targets": {
      "nutrition": { "kcal": 1800, "protein": 150, "carbs": 160, "fat": 55 },
      "mode": "grams",
      "workoutsPerWeek": 3,
      "weeklyCardioMin": 90,
      "stepsGoal": 8000,
      "goalWeightKg": 75,
      "waterMl": 3000,
      "trainingFilePlan": false,
      "nutritionFilePlan": false
    },
    "forms": [
      { "id": "cmresp00010qz8h1a2b3c4d", "type": "update", "n": 6, "filledAt": "2026-10-03T18:22:00.000Z", "handledAt": null }
    ],
    "splitDays": [
      {
        "programId": "cmf7p1q2r0001qz8h3s4t5u6v",
        "programName": "Push pull legs",
        "dayId": "d1",
        "label": "Day A",
        "exercises": [{ "exerciseId": "cmexr8s9t0004qz8h2u3v4w5x", "name": "Bench press" }]
      }
    ],
    "latestTechniqueVideos": {
      "cmexr8s9t0004qz8h2u3v4w5x": {
        "id": "cmf3a1b2c0001qz8h4d5e6f7g",
        "url": "https://media.example.com/technique/cmf3a1b2c.mp4",
        "thumbnailUrl": null,
        "status": "REVIEWED",
        "createdAt": "2026-09-20T08:14:22.000Z"
      }
    },
    "techniqueRequests": {
      "cmexr8s9t0004qz8h2u3v4w5x": "2026-10-06T09:00:00.000Z"
    }
  }
}

The slot labels in a real response are Hebrew: a meal’s custom label, or the Hebrew name of its meal type. Errors:

Code	When
`BAD_REQUEST`	`from must not be after to`, or `range must not exceed 92 days`
`NOT_FOUND`	`trainee not found`: unknown, another studio, or outside the caller’s scope
`FORBIDDEN`	Dismissed team member, or a trainee session
`VALIDATION`	Missing or malformed `from` or `to`

`POST /v1/web/checkins/trainee/:clientId/technique-request`

Asks the trainee to film one exercise in their next workout. Auth: web lane, any coach role, scoped to the trainee.

string

required

The trainee id.

string

required

Trimmed, 1 to 200 characters.

The service stamps the current time as techniqueVideo.requestedAt on every strength row that prescribes the exercise, across all of the trainee’s active training plans (stampTechniqueRequest from the program templates module). It rewrites the stored content in place. Nothing else about the plan moves, and each program’s updatedAt is written back unchanged, so the edit does not show up as a plan change. The plan version is not incremented and no plan-updated push is sent. The trainee app then shows a required technique video for that exercise in the next workout. The request clears itself once the trainee uploads a newer video of the exercise. An AuditLog row is written with action checkin.technique.requested, resource type CLIENT, and a diff holding the exercise id, the stamp, the row count and the program ids. Response:

{
  "ok": true,
  "data": { "requestedAt": "2026-10-06T09:00:00.000Z", "rowsUpdated": 2 }
}

Errors: CONFLICT with a Hebrew message when the exercise is not in any active training plan. NOT_FOUND (trainee not found). VALIDATION, FORBIDDEN.

`GET /v1/web/checkins/trainee/:clientId/insights`

Status, numbers and text per area for a date range, plus the trainee’s flags. Auth: web lane, any coach role, scoped to the trainee.

string

required

The trainee id.

string

required

ISO date or datetime.

string

required

ISO date or datetime. Inclusive. The same 92 day cap applies, because the engine calls the tracking service.

The scope check runs first, then the cache. A cached payload is never served to a coach the tracking route would refuse. On a cache miss the engine loads the tracking timeline twice, for the range and for the equal-length range right before it, computes the flags, runs every container, derives the overall verdict, and asks the model to phrase the overall text. Response:

{
  "ok": true,
  "data": {
    "overall": {
      "key": "overall",
      "status": "stuck",
      "verdict": "stuck",
      "headline": "...",
      "text": "...",
      "metrics": { "verdict": "stuck", "declining": 0, "stuck": 3, "progressing": 2 },
      "recommendation": "..."
    },
    "containers": [
      {
        "key": "weight",
        "status": "progress",
        "headline": "...",
        "text": "...",
        "metrics": { "startKg": 79.2, "endKg": 78.4, "deltaKg": -0.8 },
        "recommendation": "..."
      }
    ],
    "flags": [{ "key": "adh", "label": "...", "detail": "..." }],
    "computedAt": "2026-10-06T09:00:00.000Z"
  }
}

headline, text, recommendation, label and detail are Hebrew. The metric names inside a container’s metrics object in the example are illustrative. Each container defines its own keys. status is one of progress, stuck, decline, none. Errors: same as the tracking route. INTERNAL (insights engine is not wired) only if the controller was built without the insights service, which the router never does.

Insights engine

The engine is hybrid. Every metric, threshold, flag and per-container text is deterministic code. A model writes exactly two things: the phrasing of the overall verdict and the suggested feedback message. Both have deterministic fallback templates, so the endpoint never fails and never changes a number because of the model. The model is Anthropic, configured from ANTHROPIC_API_KEY, AGENT_MODEL and the optional ANTHROPIC_WORKSPACE_ID, with a 400 token output budget. With no key the engine always uses the fallbacks.

Nutrition adherence

dayAdherencePct mirrors the math the frontend uses, so the panel and the engine agree:

A day is logged when at least one meal is eaten or any consumed macro is above zero.
With a target, the score is the mean of min(consumed / target, 1) over protein, carbs and fat, for the macros that have a positive target. If none do, calories are used. Overshooting a macro never scores above 100%.
Without a target, the score is meals eaten over plan meals.

Note that this is a different definition from the adherence percentage in Client tracking, which counts days within 90% to 115% of the calorie target.

Containers

Key	Rule
`weight`	A change of at most 0.3% of the starting weight over the range is `stuck`. Moving toward `goalWeightKg` is `progress`, away is `decline`. With no goal, weight loss is assumed to be the aim
`calendar`	Weigh-ins at roughly one per week (`floor(span / 7)`, minimum 1) is `progress`. At least one is `stuck`. None is `decline`. A gap of more than 14 days between circumference measurements adds a note
`nutrition`	Average adherence against the previous equal range: up 3 points or more is `progress`, down 3 or more is `decline`, otherwise `stuck`. With no previous data: 80 or more is `progress`, 50 or more is `stuck`, otherwise `decline`
`workouts`	Done over planned, where planned is `span / 7 * workoutsPerWeek`: 0.9 or more is `progress`, 0.6 or more is `stuck`, below is `decline`. Without a plan, done is compared with the previous range
`steps`	Average against the steps goal: 100% or more is `progress`, 80% or more is `stuck`, below is `decline`. Without a goal, a change of 5% against the previous average decides. A Friday and Saturday dip of 20% or more adds a note
`exercise`	A planned exercise skipped two sessions in a row is `decline`. A best top-weight gain of 2.5 kg or more is `progress`. A worst drop of 2.5 kg or more is `decline`. The same top weight for three or more sessions in a row adds a stall note
`cardio`	Combined daily goal is `stepsGoal / 100 + weeklyCardioMin / 7`. Actual is `avgSteps / 100 + avgDailyCardioMin`. 90% or more is `progress`, 60% or more is `stuck`, below is `decline`. A component below 90% of its own share is called out as the missing one
`sleep`	Always `none` until a sleep source exists

For a file plan the related containers show the fixed file plan note in place of a computed text.

Overall verdict

overallStatusOf: decline if weight, nutrition or workouts is declining. Otherwise stuck when two or more containers are stuck. Otherwise progress.

Flags

Flags mark trainees who need attention. They appear as keys on queue rows and as full objects in the detail and insights payloads.

Key	Rule
`adh`	Lean adherence (meals eaten over plan meals) dropped 5 points or more in the last 14 days against the 14 days before
`weight`	The last weight of the week rose for 3 consecutive calendar weeks while the goal weight is below the current weight
`sub`	The subscription ends within the next 14 days
`skip`	A planned exercise had no done sets in the last 2 sessions of its program day

Suggested message

suggestedMessageFor produces the feedback prefill for the detail view. It takes the trainee’s first name, the plan changes since the form, and the trainee’s signals and flags. The model writes it when configured, and a deterministic template is used otherwise or on failure.

Caches

All three caches are in Redis. A Redis failure is logged as a warning and the value is computed without the cache.

Key	Lifetime	Holds
`perform:checkin-insights:<clientId>:<from>:<to>`	6 hours	The full insights payload for that exact range
`perform:checkin-flags:<clientId>`	6 hours	The trainee’s flags
`perform:checkin-suggest:<responseId>`	24 hours	The suggested message for that form

The keys do not include the data, so a payload can be up to six hours behind what the trainee logged. computedAt tells the panel how old it is.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Data model

Auth and scope

What the queue hides

Queue endpoints

`GET /v1/web/checkins`

`POST /v1/web/checkins/bulk-delete`

`GET /v1/web/checkins/:id`

`POST /v1/web/checkins/:id/feedback`

`PUT /v1/web/checkins/:id/draft`

`POST /v1/web/checkins/:id/reassign`

`POST /v1/web/checkins/:id/remind`

Trainee endpoints

`GET /v1/web/checkins/trainee/:clientId/tracking`

`POST /v1/web/checkins/trainee/:clientId/technique-request`

`GET /v1/web/checkins/trainee/:clientId/insights`

Insights engine

Nutrition adherence

Containers

Overall verdict

Flags

Suggested message

Caches

​Data model

​Auth and scope

​What the queue hides

​Queue endpoints

​GET /v1/web/checkins

​POST /v1/web/checkins/bulk-delete

​GET /v1/web/checkins/:id

​POST /v1/web/checkins/:id/feedback

​PUT /v1/web/checkins/:id/draft

​POST /v1/web/checkins/:id/reassign

​POST /v1/web/checkins/:id/remind

​Trainee endpoints

​GET /v1/web/checkins/trainee/:clientId/tracking

​POST /v1/web/checkins/trainee/:clientId/technique-request

​GET /v1/web/checkins/trainee/:clientId/insights

​Insights engine

​Nutrition adherence

​Containers

​Overall verdict

​Flags

​Suggested message

​Caches

Data model

Auth and scope

What the queue hides

Queue endpoints

`GET /v1/web/checkins`

`POST /v1/web/checkins/bulk-delete`

`GET /v1/web/checkins/:id`

`POST /v1/web/checkins/:id/feedback`

`PUT /v1/web/checkins/:id/draft`

`POST /v1/web/checkins/:id/reassign`

`POST /v1/web/checkins/:id/remind`

Trainee endpoints

`GET /v1/web/checkins/trainee/:clientId/tracking`

`POST /v1/web/checkins/trainee/:clientId/technique-request`

`GET /v1/web/checkins/trainee/:clientId/insights`

Insights engine

Nutrition adherence

Containers

Overall verdict

Flags

Suggested message

Caches