Form models - Perform

A coach builds a FormTemplate. Sending it to a trainee creates a FormAssignment. The trainee’s answers land in a FormResponse. For check-in forms the coach’s follow-up is recorded in a CheckinReview. The JSON inside schema and answers is documented in Form schema JSON.

`FormTemplate`

Table form_templates.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete. Indexed.
`type`	`FormType`	What kind of form this is.
`cadence`	`FormCadence?`	For check-in forms: `WEEKLY`, `BIWEEKLY`, `MONTHLY`.
`sendWeekday`	`Int?`	0 to 6. The day of the week the form is sent.
`sendDayOfMonth`	`Int?`	1 to 31. For the monthly cadence.
`name`	`String`
`description`	`String?`
`schema`	`Json`	The form definition: fields, pages and settings.
`logic`	`Json?`	A free-form object accepted on create and update and copied when a form is duplicated. Field and page conditions live inside `schema`, not here.
`version`	`Int`	Default `1`. Copied onto assignments and responses as `formVersion`.
`status`	`FormStatus`	Default `DRAFT`.
`active`	`Boolean`	Default `true`. An inactive form is never sent, pickers hide it, and assigning it fails with `FORM_INACTIVE`.
`createdAt`, `updatedAt`	`DateTime`

Relations: responses, assignments, automationHooks, and four named back-relations that say where the form is wired in:

Relation	From	Meaning
`onboardingForProducts`	`Product.onboardingFormId`	Onboarding form of a plan.
`updateForProducts`	`Product.updateFormId`	Check-in form of a plan.
`onboardingForClients`	`Client.onboardingFormId`	Per-trainee onboarding override.
`updateForClients`	`Client.updateFormId`	Per-trainee check-in override.

All four are SetNull on the referencing side, so deleting a form clears the pointers.

`FormType`

Value	Meaning
`INTAKE`	Onboarding questionnaire.
`CHECK_IN`	Recurring update form.
`ONE_TIME`	Sent once, on demand.
`PDF_SIGNATURE`	A coach-made PDF the trainee signs through a public link, never inside the app.

`FormStatus`

DRAFT, PUBLISHED, ARCHIVED.

`FormCadence`

WEEKLY, BIWEEKLY, MONTHLY. The same enum is used on Client.updateCadence. The next-date math is mirrored between the web app and the backend, so change both.

`DefaultFormTemplate`

Table default_form_templates. Global starter forms managed by super admins.

Field	Type	Meaning
`key`	`String`	Unique. Stable identifier of the starter form.
`type`	`FormType`
`name`, `description`	`String`, `String?`
`schema`	`Json`	Same shape as `FormTemplate.schema`.
`active`	`Boolean`	Default `true`.
`order`	`Int`	Default `0`.
`createdAt`, `updatedAt`	`DateTime`

No tenant. Every newly provisioned studio receives a copy of the active rows. Editing a row here affects only studios created afterwards.

`FormAssignment`

Table form_assignments. One send of a form to one trainee.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`formTemplateId`	`String`	Cascade delete.
`clientId`	`String`	Cascade delete.
`formVersion`	`Int`	Default `1`. The template version at send time.
`status`	`FormAssignmentStatus`	Default `PENDING`.
`assignedById`	`String?`	Who sent it.
`prompt`	`String?`	Optional message shown to the trainee with the form.
`dueAt`	`DateTime?`
`notifiedAt`	`DateTime?`	When the trainee was notified. The `(status, notifiedAt)` index is what the pending-form notifier scans.
`completedAt`	`DateTime?`
`signToken`	`String?`	Unique. `PDF_SIGNATURE` only: the token in the public signing link.
`prefill`	`Json?`	`PDF_SIGNATURE` only: the coach-filled field values as an object of key to string. Only non-blank values are stored.
`signSchema`	`Json?`	`PDF_SIGNATURE` only: the form schema as it was when sent. The link signs that version even after the coach edits the form.
`createdAt`, `updatedAt`	`DateTime`

Indexes: studioId, (clientId, status), formTemplateId, (studioId, clientId, createdAt), (status, notifiedAt).

`FormAssignmentStatus`

PENDING, COMPLETED, CANCELLED.

`FormResponse`

Table form_responses. A submitted form.

Field	Type	Meaning
`formTemplateId`	`String`	Cascade delete.
`assignmentId`	`String?`	The assignment it answers. Null for a response with no assignment.
`clientId`	`String`	Cascade delete.
`formVersion`	`Int`	Default `1`.
`answers`	`Json`	Object keyed by field `key`.
`schemaSnapshot`	`Json?`	The schema the trainee actually answered. Readers use `schemaSnapshot ?? formTemplate.schema`, so old responses still render correctly after the form is edited.
`handledNote`	`String?`	The coach’s “what I changed” note, written when the form task is handled. It belongs to the submission, not to the task, and history reads it long after the task is gone.
`handledById`, `handledByName`	`String?`	Who handled it.
`handledAt`	`DateTime?`
`documentUrl`	`String?`	`PDF_SIGNATURE` only: public URL of the signed PDF.
`signingAudit`	`Json?`	`PDF_SIGNATURE` only. See below.
`submittedAt`	`DateTime?`
`createdAt`	`DateTime`

Indexes: formTemplateId, assignmentId, clientId, (clientId, submittedAt), (clientId, createdAt). There is no studioId. Scope through the client or the template.

Side effects of a submission

forms.service.ts does more than insert the row:

Answers of fields whose type is in CLIENT_SAVE_TYPES and that have saveToClient on are written to the trainee: height to Client.heightCm, birth_date to Client.birthDate, goal to Client.goal (the option’s label), weight to a WeightEntry with source: 'form' and formResponseId, body_measurement merged into DailyMetric.measurements, image_upload to a ClientPhoto with the field’s config.pose.
A food_preferences answer updates Client.foodPreferences.
The form-filled automation and outbound webhook fire. See Outbound webhooks.

`signingAudit`

Written by apps/core-api/src/modules/form-sign/form-sign.service.ts:

{
  "signedAt": "2026-10-07T09:12:44.120Z",
  "ip": "CLIENT_IP",
  "userAgent": "BROWSER_USER_AGENT",
  "phone": "TRAINEE_PHONE",
  "documentSha256": "SHA256_OF_SOURCE_PDF",
  "signedDocumentSha256": "SHA256_OF_SIGNED_PDF"
}

Document signing flow

PDF_SIGNATURE forms are signed on a public page, with no user session. The 128-bit signToken in the path is the credential. The router is mounted at /v1/public/sign (PUBLIC_SIGN_MOUNT):

Route	Purpose
`GET /v1/public/sign/:token`	Page data: the schema as sent and the coach’s prefill.
`GET /v1/public/sign/:token/document`	The source PDF. Browsers cannot read the CDN cross-origin, so pdf.js loads it through the API.
`POST /v1/public/sign/:token`	Submit. Body: `values` (key to string, each up to 5000 characters) and `signatures` (key to image data, each up to 600000 characters).
`GET /v1/public/sign/:token/signed`	The signed copy.

Responses on this lane are plain JSON, not the usual ok and data envelope, because the web app’s proxy relays them to the page as they are. The lane keeps its own per-link and per-visitor rate counters, since every request reaches the API from the proxy’s single address. A forwarded client IP is believed only on a request the proxy signed. On submit the service stamps the values and signatures onto the PDF, stores the result, and creates the FormResponse with documentUrl and signingAudit.

`CheckinReview`

Table checkin_reviews. One check-in queue review per submitted form.

Field	Type	Meaning
`responseId`	`String`	Unique. The `FormResponse` being reviewed. Plain id with no foreign key.
`studioId`	`String`	Tenant. Indexed.
`clientId`	`String`	Indexed.
`assignedCoachId`	`String?`	An admin reassignment. Overrides the trainee’s coach for this form only.
`draft`	`Json?`	The coach’s autosaved draft. See below.
`note`	`String?`	Internal write-up of what was done. For the team only, never sent to the trainee.
`message`	`String?`	The feedback sent to the trainee.
`channels`	`String[]`	Channels the feedback went out on: `push`, `whatsapp`.
`attachedChanges`	`Json?`	Plan-change links attached to the feedback. Written only when feedback is actually sent.
`handledById`, `handledByName`	`String?`
`handledAt`	`DateTime?`	When the review was completed.
`remindedAt`	`DateTime?`	Last reminder to the trainee.
`dismissedAt`	`DateTime?`	Taken off the queue by a coach. This hides the form from the queue only. The response and the review stay as the trainee’s history.
`createdAt`, `updatedAt`	`DateTime`

This model has no relations on purpose. It is fully separate from the Work Board’s FORM_FILLED tasks.

`draft`

Validated by draftBody in apps/core-api/src/modules/checkins/checkins.schema.ts:

{
  "note": "Raised calories by 150",
  "sendToTrainee": true,
  "message": "Great week. I raised your calories a little.",
  "channels": ["push"],
  "attachedChangeIds": ["CHANGE_ID"]
}

A draft may be half-written. Only the shape is enforced so autosave never bounces. Completing the review uses feedbackBody, which adds the real rules: with sendToTrainee on, a message and at least one channel are required. Without it, the internal note must be non-empty. Older web clients send the legacy shape without sendToTrainee. The withLegacySend preprocess reads a non-empty message or channel list as “send”. Stored drafts are normalized the same way on read.

`FormReminderSend`

Table form_reminder_sends. The ledger behind form reminders.

Field	Type	Meaning
`studioId`	`String`	Indexed.
`clientId`	`String`
`instanceKey`	`String`	Identifies one pending form instance.
`messageId`	`String`	Identifies one configured reminder message.
`sentAt`	`DateTime`	Default `now()`. Indexed.

Unique on (instanceKey, messageId). Each configured reminder message is sent at most once per form instance. The reminder engine inserts first and treats a unique violation as “already sent”. The messages themselves are configured in NotificationTypeConfig.messages and StudioNotificationConfig.messages for the FORM_SENT and FORM_REMINDERS types. See Messaging and notifications.

​FormTemplate

​FormType

​FormStatus

​FormCadence

​DefaultFormTemplate

​FormAssignment

​FormAssignmentStatus

​FormResponse

​Side effects of a submission

​signingAudit

​Document signing flow

​CheckinReview

​draft

​FormReminderSend