Studios and coaches

These models are in the public schema and appear in both Prisma schema files.

`Studio`

Table studios. The tenant root. Every domain row hangs off a studio, directly or through a client.

Field	Type	Meaning
`id`	`String`	cuid. This is the `studioId` every other table references.
`externalOrgId`	`String?`	Unique. The better-auth `Organization.id` this studio belongs to. No foreign key.
`name`	`String`	Studio name.
`slug`	`String`	Unique.
`locale`	`String`	Default `he`.
`timezone`	`String`	Default `Asia/Jerusalem`. Used to decide what “today” means for studio-level jobs.
`branding`	`Json?`	Brand skin for the trainee app. See Studio settings JSON.
`settings`	`Json?`	Free-form settings bag. See Studio settings JSON.
`createdAt`, `updatedAt`	`DateTime`
`deletedAt`	`DateTime?`	Soft delete. An archived studio’s API keys stop working even before they are revoked, and the trainee lane checks it when resolving a session.

How a studio row is created

The web lane middleware webUserContext (apps/core-api/src/middleware/web-context.ts) resolves x-studio-id, which carries the organization id, to a studio. If none exists it creates one with externalOrgId, name, slug and the default content categories. It then upserts the calling owner as a HEAD_COACH in ensureOwnerCoach. Results are cached in memory per process.

Relations

Studio has a back-relation to nearly every studio-scoped model. All of them cascade on studio delete. In practice studios are archived with deletedAt, and a hard delete goes through the admin purge recorded in AdminDeletion (see CRM, audit and misc).

`StudioApiKey`

Table studio_api_keys. A studio-scoped secret for the partner API, the automation API and the MCP server.

Field	Type	Meaning
`studioId`	`String`	Owner. Cascade delete. Indexed.
`name`	`String`	Label the coach typed, 1 to 100 characters.
`keyHash`	`String`	Unique. SHA-256 hex digest of the secret (`hashPartnerKey`). The plaintext is never stored.
`prefix`	`String`	The first 15 characters of the secret, kept so the settings page can show which key is which.
`scopes`	`String[]`	Default `["panel"]`.
`lastUsedAt`	`DateTime?`	Coarse usage stamp. Written at most once per 5 minutes per key (`LAST_USED_THROTTLE_MS`).
`revokedAt`	`DateTime?`	Set on revoke. A revoked key is rejected. Rows are kept for history.
`createdAt`	`DateTime`

Relations: studio, and automationHooks. A hook belongs to the key that registered it and is deleted with it. Lifecycle: created and revoked from the web lane at /v1/web/studios/current/api-keys by OWNER or HEAD_COACH. The create response is the only place the plaintext secret appears. Details are in Partner API and studio API keys.

`Coach`

Table coaches. A staff member inside one studio.

Field	Type	Meaning
`studioId`	`String`	Tenant. Cascade delete. Indexed.
`externalUserId`	`String?`	The auth `User.id`. Null for a directory entry that has no login yet.
`role`	`CoachRole`	Default `SUB_COACH`.
`name`	`String`	Display name.
`firstName`, `lastName`	`String?`	Split name, when captured.
`roleTitle`	`String?`	Free-text job title shown on the team page.
`permissionGroup`	`String?`	Name of the permission preset picked in the team dialog.
`permissions`	`Json?`	The `coachPermissions` object. See below.
`lastActiveAt`	`DateTime?`	Stamped by the web lane, throttled to one write per coach per 5 minutes.
`email`	`String`
`phone`	`String?`
`healthScore`	`Int?`	Optional integer accepted by the coach create and update schemas. No other code reads it.
`active`	`Boolean`	Default `true`. A dismissed team member is set inactive, not deleted.
`createdAt`, `updatedAt`	`DateTime`

Unique on (studioId, externalUserId). Index on studioId. Relations: clients (legacy single-coach link through Client.coachId), clientAssignments (ClientCoach), inboxItems, leads (as Lead.ownerCoachId).

`CoachRole`

Value	Meaning
`HEAD_COACH`	Admin of the studio. Bypasses every permission in the `permissions` blob. Owners are provisioned with this role.
`SUB_COACH`	A regular team member, narrowed by `permissions`.

`Coach.permissions`

Validated by coachPermissions in apps/core-api/src/modules/coaches/coaches.schema.ts:

{
  "trainees": "assigned",
  "plans": "useTemplates",
  "forms": "view",
  "content": "view",
  "subscriptions": "assign",
  "discount": { "enabled": false, "maxPercent": 5 }
}

Key	Values	Default
`trainees`	`assigned`, `all`	`assigned`
`plans`	`useTemplates`, `manageTemplates`	`useTemplates`
`forms`	`view`, `manage`	`view`
`content`	`view`, `manage`	`view`
`subscriptions`	`assign`, `manage`	`assign`
`discount.enabled`	boolean	`false`
`discount.maxPercent`	integer 5 to 100	`5`

readCoachPermissions(role, stored) is the only reader. Its rules:

HEAD_COACH always gets UNRESTRICTED_COACH_PERMISSIONS.
A SUB_COACH with no stored blob also gets unrestricted permissions. Coaches created before the permission model existed could see the whole studio, and restricting them on deploy would have cut them off from their trainees.
A blob that fails to parse falls back to unrestricted.
Only a member configured through the team screen is narrowed.

`ClientCoach`

Table client_coaches. The many-to-many assignment of coaches to trainees.

Field	Type	Meaning
`studioId`	`String`	Tenant. Indexed. No relation field, it is a plain column for filtering.
`clientId`	`String`	Cascade delete. Indexed.
`coachId`	`String`	Cascade delete. Indexed.
`createdAt`	`DateTime`

Unique on (clientId, coachId). Client.coachId still exists as the older single-coach column and relation. Treat ClientCoach as the full list of a trainee’s coaches. It is what trainee scoping for a trainees: "assigned" coach, joint tasks and the coach multi-select read.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Studios and coaches

`Studio`

How a studio row is created

Relations

`StudioApiKey`

`Coach`

`CoachRole`

`Coach.permissions`

`ClientCoach`

​Studio

​How a studio row is created

​Relations

​StudioApiKey

​Coach

​CoachRole

​Coach.permissions

​ClientCoach

`Studio`

How a studio row is created

Relations

`StudioApiKey`

`Coach`

`CoachRole`

`Coach.permissions`

`ClientCoach`