Messaging and notification models

Three separate systems live here:

WhatsApp, in the public schema.
Trainee push notifications, in the public schema.
The coach web app’s notification bell, in the auth schema.

`WhatsappTemplate`

Table whatsapp_templates. A message template the studio wrote in Perform.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete. Indexed.
`name`	`String`
`body`	`String`	Text with `{{variable}}` placeholders. `applyVariables` replaces each with the supplied value, or an empty string.
`variables`	`String[]`	The placeholder names.
`smartsendTemplateId`	`String?`	Id of a matching approved template at SmartSend, when there is one.
`status`	`String?`
`createdAt`, `updatedAt`	`DateTime`

These are Perform-side text templates. Approved WhatsApp Business templates live in the studio’s SmartSend account and are listed live through the SmartSend API. They are not stored here.

`WhatsappMessage`

Table whatsapp_messages. A log of messages sent and received.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`clientId`	`String?`	The trainee, when the phone number matched one. The relation has no `onDelete` rule. Trainee account deletion removes these rows explicitly.
`templateId`	`String?`	The template used, if any.
`direction`	`MessageDirection`	`INBOUND` or `OUTBOUND`.
`body`	`String?`
`status`	`MessageStatus`	Default `QUEUED`.
`externalId`	`String?`	Provider message id.
`payload`	`Json?`	For inbound messages, the parsed provider message. For a failed outbound message, `{ "error": "..." }`.
`createdAt`, `updatedAt`	`DateTime`

Indexes: studioId, clientId, (clientId, createdAt), (studioId, createdAt).

`MessageStatus`

Value	Meaning
`QUEUED`	Default.
`SENT`	The provider accepted the message. `sendToClient` writes this after a successful send.
`DELIVERED`, `READ`	Defined in the enum. The current service does not process delivery status callbacks, so it does not write them.
`FAILED`	The send threw. The row is still written, with the error in `payload`.

An inbound message from a known trainee also creates an InboxItem of type MESSAGE with refId pointing at the message row.

Trainee push

`TraineePushToken`

Table trainee_push_tokens. One row per device.

Field	Type	Meaning
`clientId`	`String`	Cascade delete. Indexed.
`token`	`String`	The Expo push token, up to 300 characters.
`platform`	`String?`	`ios` or `android`. Null for installs that registered before the app reported it.
`createdAt`, `updatedAt`	`DateTime`

Unique on (clientId, token). Lifecycle:

Registered by POST /v1/trainee/push-token, removed by DELETE /v1/trainee/push-token.
Pruned by prunePushTokens when Expo reports DeviceNotRegistered, on a ticket or on a receipt.
Deleted explicitly when a trainee deletes their account, because that is a soft delete and the cascade never fires.

`NotificationConfigType`

Fifteen values. Twelve are active (ACTIVE_NOTIFICATION_TYPES in notification-configs.schema.ts).

Value	Mute group	Active
`TRAINER_MESSAGE`	`COACH_MESSAGES`	yes
`FORM_ASSIGNED`	`FORMS`	no
`REST_TIMER`	`WORKOUT_REMINDERS`	yes
`WORKOUT_IDLE`	`WORKOUT_REMINDERS`	yes
`WORKOUT_UNFINISHED`	`WORKOUT_REMINDERS`	yes
`CHECK_IN_DUE`	`CHECK_INS`	no
`CHECK_IN_TOMORROW`	`CHECK_INS`	no
`TRAINING_PLAN_UPDATED`	`PLANS`	yes
`TRAINING_PLAN_ASSIGNED`	`PLANS`	yes
`NUTRITION_PLAN_UPDATED`	`PLANS`	yes
`NUTRITION_PLAN_ASSIGNED`	`PLANS`	yes
`SUBSCRIPTION_FROZEN`	`SUBSCRIPTION`	yes
`SUBSCRIPTION_RENEWED`	`SUBSCRIPTION`	yes
`FORM_SENT`	`FORMS`, or `CHECK_INS` when the form is a check-in	yes
`FORM_REMINDERS`	`CHECK_INS` for check-in forms, otherwise `FORMS`	yes

The three workout reminder types are scheduled on the device by the app. The server only supplies their text.

`NotificationTypeConfig`

Table notification_type_configs. The global default for each type. Managed through /v1/admin/notification-configs with service auth.

Field	Type	Meaning
`type`	`NotificationConfigType`	Unique. One row per type.
`enabled`	`Boolean`	Default `true`.
`titleTemplate`	`String`	Supports `{{variable}}` tokens.
`bodyTemplate`	`String`
`sound`	`Boolean`	Default `true`.
`sendTime`	`String?`	`HH:mm`.
`messages`	`Json?`	For multi-message types. See below.
`createdAt`, `updatedAt`	`DateTime`

`StudioNotificationConfig`

Table studio_notification_configs. A studio’s override of one type. Same columns as the global row plus studioId. Unique on (studioId, type). Index on studioId. resolveNotificationConfig in apps/core-api/src/lib/trainee-push.ts picks the studio row, then the global row, then the code defaults in NOTIFICATION_CONFIG_DEFAULTS.

`messages`

Most types are single: one title and body, taken from titleTemplate and bodyTemplate. Two types hold several messages in the messages column, validated by notificationMessage:

[
  {
    "id": "form-check-in",
    "enabled": true,
    "formType": "CHECK_IN",
    "title": "Your check-in is ready",
    "subtitle": "It takes two minutes.",
    "offsetDays": 1,
    "time": "10:00",
    "onlyIfNotFilled": true,
    "opens": "form"
  }
]

Key	Type	Used by	Meaning
`id`	string, up to 40	both	Stable id. `FormReminderSend.messageId` references it.
`enabled`	boolean	both
`title`	string, up to 300	both
`subtitle`	string, up to 1500	both	The body.
`formType`	`ALL`, `INTAKE`, `CHECK_IN`	`FORM_SENT`	Which forms the message is for. `pickFormSentMessage` prefers an exact type match and falls back to `ALL`.
`offsetDays`	integer, -3 to 3	`FORM_REMINDERS`	Days relative to the form’s due day.
`time`	`HH:mm`	`FORM_REMINDERS`	Time of day.
`onlyIfNotFilled`	boolean	`FORM_REMINDERS`	Skip when the form was already filled.
`opens`	`home` or `form`	`FORM_REMINDERS`	Where the push leads.

Limits from NOTIFICATION_CATALOGUE: up to 3 messages for FORM_SENT (MAX_FORM_SENT_MESSAGES) and up to 10 for FORM_REMINDERS (MAX_FORM_REMINDERS). The replace endpoint accepts 1 to 20. When the stored messages value does not parse, messagesOf falls back to the code defaults for that type.

Trainee mute groups

Client.mutedNotificationGroups holds the groups a trainee switched off in the app: CHECK_INS, FORMS, PLANS, WORKOUT_REMINDERS, COACH_MESSAGES, SUBSCRIPTION. isNotificationMuted(type, mutedGroups, formType) maps a type to its group with notificationGroupFor. COACH_MESSAGES is in LOCKED_NOTIFICATION_GROUPS and can never be muted, whatever the array says. A muted recipient is reported in the muted list of the send result. It is not counted as a failure. Sending, tickets and receipts are covered in Push notifications.

Coach web notifications

These live in the auth schema and are declared only in packages/database. The code is in packages/notifications.

`Notification`

Table auth.notification.

Field	Type	Meaning
`userId`	`String`	Recipient. Cascade delete. Indexed.
`type`	`NotificationType`	`WELCOME` or `APP_UPDATE`.
`data`	`Json`	Default `{}`. Free-form. The email path reads `headline` or `title`, and `message`, from it.
`link`	`String?`	Absolute link, resolved by `resolveNotificationLink`.
`read`	`Boolean`	Default `false`.
`createdAt`, `updatedAt`	`DateTime`

`UserNotificationPreference`

Table auth.user_notification_preference. A row means the user turned that type off for that target.

Field	Type	Meaning
`userId`	`String`	Cascade delete.
`type`	`NotificationType`
`target`	`NotificationTarget`	`IN_APP` or `EMAIL`.
`createdAt`	`DateTime`

Unique on (userId, type, target). createNotification in packages/notifications/src/create-notification.ts checks isNotificationDisabled for each target. It inserts the in-app row unless in-app is disabled, and sends the notification email template unless email is disabled. The settings page groups come from NOTIFICATION_GROUPS in packages/notifications/src/catalog.ts. Today there is one group, general, containing APP_UPDATE. The bell in the web app’s navigation bar reads these rows through the oRPC procedures notifications.unreadCount and notifications.list. The queries are in packages/database/prisma/queries/notifications.ts.

Coach tasks on the Work Board are a different thing. They are InboxItem rows in the public schema. See Automation and tasks.

​WhatsApp

​WhatsappTemplate

​WhatsappMessage

​MessageStatus

​Trainee push

​TraineePushToken

​NotificationConfigType

​NotificationTypeConfig

​StudioNotificationConfig

​messages

​Trainee mute groups

​Coach web notifications

​Notification

​UserNotificationPreference

WhatsApp

`WhatsappTemplate`

`WhatsappMessage`

`MessageStatus`

Trainee push

`TraineePushToken`

`NotificationConfigType`

`NotificationTypeConfig`

`StudioNotificationConfig`

`messages`

Trainee mute groups

Coach web notifications

`Notification`

`UserNotificationPreference`