Automation and task models

A coach’s Work Board is a list of InboxItem rows. Most are created by automations: one TaskAutomation per trigger type per studio, each with either a simple list of task blocks or a node flow. A flow that waits or branches is tracked by an AutomationFlowRun. The JSON columns on this page are documented in Automation JSON.

`InboxItem`

Table inbox_items. One task or notification for the coaching team.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`coachId`	`String?`	Legacy single assignee. `SetNull` on coach delete.
`coachIds`	`String[]`	Default `[]`. All assignees. GIN indexed. An empty array with no `coachId` means the task is visible to the whole team.
`clientId`	`String?`	The trainee the task is about. Cascade delete.
`type`	`InboxItemType`	What kind of task.
`refId`	`String?`	The entity the task points at, for example a WhatsApp message id.
`title`, `detail`	`String?`
`source`	`String`	Default `manual`. Automations write `auto`.
`autoKey`	`String?`	Idempotency key for automated tasks. Unique per studio.
`dueAt`	`DateTime?`
`metadata`	`Json?`	Small string map with context for the task.
`priority`	`Int`	Default `0`.
`status`	`InboxItemStatus`	Default `OPEN`.
`snoozeUntil`	`DateTime?`
`resolvedAt`	`DateTime?`
`createdAt`, `updatedAt`	`DateTime`

Unique on (studioId, autoKey). Indexes: (studioId, status), (studioId, status, priority, createdAt), coachId, clientId, (clientId, status), GIN on coachIds.

`autoKey`

The task generator (apps/core-api/src/modules/tasks/task-generator.ts) builds a key from the trigger type and the entity it fired for, then inserts. The unique constraint makes the same trigger firing twice for the same entity a no-op.

Trigger about	Key form
A form response	`<TYPE>:<formResponseId>` plus a suffix
A technique video	`<TYPE>:<videoId>` plus a suffix
A trainee	`<TYPE>:<clientId>` plus a suffix

The suffix distinguishes the several tasks one trigger can fan out into. A task created by a flow node ends with :fx:<nodeId>.

`InboxItemType`

Value	Meaning
`MESSAGE`	An inbound WhatsApp message from a trainee.
`TECHNIQUE_VIDEO`	A technique video is waiting for review.
`FORM_RESPONSE`	Legacy form response task.
`FORM_FILLED`	A trainee submitted a form.
`FORM_FILLED_OVERDUE`	A filled form has not been handled in time.
`FORM_SENT`	A form was sent and not yet filled.
`FORM_FEEDBACK_SENT`	The coach sent feedback on a check-in or onboarding form.
`FORM_RATING_BELOW`	A rating answer fell below the configured score.
`CHURN_RISK`
`MISSED_CHECK_IN`
`NO_WORKOUT`	No workout logged for longer than the threshold for the trainee’s weekly frequency.
`INACTIVE`	The trainee has not opened the app.
`PLAN_EXPIRING`	The subscription is about to end.
`MILESTONE`
`MISSED_STREAK`
`NEW_CLIENT_IN_PLAN`	A new trainee was assigned a plan.
`SUBSCRIPTION_ASSIGNED`	A subscription was assigned.
`CALORIE_UNDER`, `CALORIE_OVER`	Logged calories deviate from the target by more than the configured percentage.
`AEROBIC_UNDER`	Cardio is below the plan requirement.
`PAUSED_DURATION`	The trainee has been frozen for longer than the threshold.
`TRAINING_PLAN_STALE`, `NUTRITION_PLAN_STALE`	The plan has not been updated for longer than the threshold.
`MANUAL`	Created by hand, by a coach or through the API.

The types an automation can be configured for are TASK_TRIGGER_TYPES in task-automations/task-automations.schema.ts. That list leaves out MESSAGE, CHURN_RISK, MISSED_CHECK_IN, MISSED_STREAK and MANUAL.

`InboxItemStatus`

OPEN, SNOOZED (with snoozeUntil), DONE, DISMISSED. The scheduler also closes automated tasks whose condition no longer holds.

`TaskAutomation`

Table task_automations. A studio’s configuration for one trigger type.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`type`	`InboxItemType`	The trigger. Unique per studio.
`enabled`	`Boolean`	Default `false`.
`thresholdValue`	`Int`	Default `0`. Mirrors the primary task’s threshold.
`thresholdUnit`	`String`	Default `days`. One of `minutes`, `hours`, `days`, `percent`, `score`.
`thresholdByFrequency`	`Json?`	`NO_WORKOUT` only. Days without a workout per weekly-frequency band.
`assigneeMode`	`TaskAssigneeMode`	Default `RESPONSIBLE`.
`assigneeCoachId`	`String?`	Legacy single assignee.
`assigneeCoachIds`	`String[]`	Assignees for `SPECIFIC` mode.
`notify`	`Boolean`	Default `false`. Also notify the trainee.
`notifyTitle`, `notifyBody`	`String?`	Trainee notification text.
`planIds`	`String[]`	Limit the trigger to trainees on these plans. Empty means all.
`flow`	`Json?`	The node flow the builder edits. Null means the automation was never opened in the builder, and readers synthesize a flow from the legacy task blocks.
`createdAt`, `updatedAt`	`DateTime`

Unique on (studioId, type). Index on studioId.

`TaskAssigneeMode`

Value	Who gets the task
`OWNER`	The studio manager.
`RESPONSIBLE`	The trainee’s own coaches, from `ClientCoach`. A joint task is one row listing every assigned coach.
`SPECIFIC`	The coaches in `assigneeCoachIds`. With no ids it is visible to the whole team.
`UNASSIGNED`	No owner. The task sits on the Work Board for anyone to claim. The default for task nodes in the flow builder.

`TaskAutomationTask`

Table task_automation_tasks. One task block under an automation. A trigger fans out into up to MAX_TASKS_PER_AUTOMATION (5) tasks.

Field	Type	Meaning
`automationId`	`String`	Cascade delete.
`ordinal`	`Int`	Default `0`. Position. Unique per automation. Ordinal 0 is the primary task: it keeps the legacy `autoKey` form so tasks created before the fan-out existed are not duplicated, and its settings mirror onto the parent row.
`thresholdValue`, `thresholdUnit`	`Int`, `String`	When this task fires relative to the trigger.
`assigneeMode`	`TaskAssigneeMode`	Default `RESPONSIBLE`.
`assigneeCoachIds`	`String[]`
`name`	`String?`	Task title, up to 120 characters.
`notify`	`Boolean`	Default `false`.
`notifyBody`	`String?`	Deliberately unbounded so messages that predate the 500 character UI cap can still be saved.
`formTypes`	`FormType[]`	Default `[INTAKE, CHECK_IN, ONE_TIME]`. For form triggers: which form types this task applies to.
`formIds`	`String[]`	Narrow further to specific forms. Up to 500.
`createdAt`, `updatedAt`	`DateTime`

Unique on (automationId, ordinal).

The column default for formTypes lists three form types. The Zod default in automationTaskBody lists all four, including PDF_SIGNATURE. Rows written through the API get four. Rows inserted any other way get three.

`AutomationFlowRun`

Table automation_flow_runs. One execution of an automation’s flow for one trigger entity.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`type`	`InboxItemType`	The trigger type.
`clientId`	`String?`	The trainee. Plain id.
`entityKey`	`String`	The entity the run is for, in suffix-free `autoKey` form, for example `INACTIVE:<clientId>` or `FORM_FILLED:<responseId>`.
`status`	`String`	`RUNNING` (default), `WAITING`, `DONE` or `FAILED`.
`position`	`Json`	Default `[]`. The work stack of execution frames a resume picks up from.
`context`	`Json`	Default `{}`. Facts frozen at trigger time.
`resumeAt`	`DateTime?`	When a `WAITING` run’s wait elapses.
`error`	`String?`
`createdAt`, `updatedAt`	`DateTime`
`finishedAt`	`DateTime?`

Unique on (studioId, type, entityKey). This makes starts idempotent, exactly like the autoKey contract: the same trigger firing again for the same entity does not start a second run. Indexes: (status, resumeAt), which the sweeper scans, and (studioId, status).

Lifecycle

Two things resume a waiting run. A delayed BullMQ job on the flow-run queue is the fast path. An hourly repeatable job on the flow-sweep queue is the durable path: it picks up runs whose resumeAt has passed, so a wait survives a Redis flush. On failure the position is preserved.

`FlowNodeExecution`

Table flow_node_executions. The retry and dedup ledger for a run.

Field	Type	Meaning
`runId`	`String`	Cascade delete.
`nodeId`	`String`	The flow node that ran.
`executedAt`	`DateTime`	Default `now()`.
`result`	`Json?`	What the node produced.

Unique on (runId, nodeId). The executor inserts the row first and treats a unique violation (P2002) as “already executed”. A crash followed by a retry can therefore never send the same push, WhatsApp message or webhook twice.

`AutomationHook`

Table automation_hooks. A webhook an automation platform registered for one studio event.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete.
`apiKeyId`	`String`	The `StudioApiKey` that registered it. Cascade delete, so revoking by deleting a key drops its hooks. Indexed.
`event`	`String`	The event. Today only `FORM_FILLED` (`HOOK_EVENTS`).
`targetUrl`	`String`	Where deliveries go. Must be `https` on a public host.
`formTemplateId`	`String?`	Null means every form. A value narrows the hook to one form. Cascade delete with the form.
`secret`	`String`	Random signing secret. Returned once, on registration.
`active`	`Boolean`	Default `true`.
`lastDeliveryAt`	`DateTime?`
`lastStatus`	`Int?`	HTTP status of the last delivery.
`failureCount`	`Int`	Default `0`. Incremented on a failed delivery and reset to 0 on success.
`createdAt`, `updatedAt`	`DateTime`

Index: (studioId, event, active). A row here is a live subscription, not configuration a coach maintains. Make creates it when a scenario’s instant trigger is switched on and deletes it when the trigger is switched off. See Outbound webhooks.

`AutomationRule`

Table automation_rules. The original automation model.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete. Indexed.
`name`	`String`
`trigger`	`Json`	Free-form object.
`action`	`Json`	Free-form object.
`enabled`	`Boolean`	Default `true`.
`createdAt`, `updatedAt`	`DateTime`

The automation module at /v1/web/automation is plain CRUD over this table. Its schema accepts any object for trigger and action (z.record(z.string(), z.unknown())). The automations that actually run today are TaskAutomation rows, driven by the task scheduler and the flow executor.

Queues involved

Queue name	Constant	Job
`automation-evaluate`	`PerformQueue.AUTOMATION_EVALUATE`	Hourly repeatable job in `workers/task-scheduler.ts` that generates and auto-closes tasks.
`flow-run`	`PerformQueue.FLOW_RUN`	Advances one flow run per job.
`flow-sweep`	`PerformQueue.FLOW_SWEEP`	Hourly sweep that resumes due waiting runs.
`automation-hook-deliver`	`PerformQueue.AUTOMATION_HOOK_DELIVER`	Delivers webhooks, both registered hooks and flow webhook nodes.

​InboxItem

​autoKey

​InboxItemType

​InboxItemStatus

​TaskAutomation

​TaskAssigneeMode

​TaskAutomationTask

​AutomationFlowRun

​Lifecycle

​FlowNodeExecution

​AutomationHook

​AutomationRule

​Queues involved

`InboxItem`

`autoKey`

`InboxItemType`

`InboxItemStatus`

`TaskAutomation`

`TaskAssigneeMode`

`TaskAutomationTask`

`AutomationFlowRun`

Lifecycle

`FlowNodeExecution`

`AutomationHook`

`AutomationRule`

Queues involved