Organizations — Behavior

State

No explicit status enum. Lifecycle is conveyed by:

platform_tier_updated_at tracks the most recent tier change (set by the platform-billing module, not by this one).

Invariants

• One Clerk org per FitKit org — clerk_organization_id UNIQUE.
• Slug uniqueness — slug UNIQUE NOT NULL. Auto-generated as slugify(name) + '-' + 6char-random.
• Caller becomes owner on create — POST /organizations always inserts a memberships row with role='owner', status='active'.
• Owner protection on membership update — flipping the last owner away from owner or to suspended/cancelled is rejected by MembershipsService.updateMembership. (No similar guard on DELETE /users/me self-delete; see Known Gaps in README.)
• Onboarding-complete is owner-only — even admins are rejected.
• Logo upload size 2MB max, MIME ∈ {jpeg, png, webp}. The r2Key is fixed to orgs/${orgId}/logo. Existing logos are overwritten in place.
• Defense-in-depth on logo confirm — confirm checks both the Redis upload-session blob (signals upload was initiated) AND r2.objectExists(r2Key) (signals the bytes actually landed).
• Timezone default: UTC (overrideable on create). Currency default: USD.
• Cancellation policy defaults: cancellationWindowHours=2, allowLateCancellation=false.

Golden paths

G1 — Owner onboarding (create org)

1. Wizard step “org”: user enters name + org type. (See onboarding.)
2. Wizard handleFinish calls POST /organizations with {name, type}.
3. Service:
   • Calls usersService.findOrCreateFromClerk(clerkId) to ensure the caller has a DB row.
   • Calls clerk.organizations.createOrganization({name, slug, createdBy: clerkId}) — the Clerk side adds the caller as org:admin automatically.
   • Inserts organizations row with default tier lite.
   • Inserts owner memberships row.
4. Legal consents POST (/legal/consents) immediately follows.
5. Wizard calls POST /:id/onboarding-complete with empty body (default — no class type, no invites) and the welcome email is sent.

G2 — Update branding

1. PATCH /organizations/:id with {name, description, contactEmail, contactPhone, website, logoUrl}.
2. All fields conditional on !== undefined; empty string for contactEmail/Phone/website/logoUrl is normalized to null.

G3 — Logo upload

1. Web: user picks file. POST /:id/logo/upload-url with {mimeType, fileSize}.
2. Server validates MIME + size; generates presigned R2 PUT URL; stashes {r2Key, mimeType} in Redis under upload:logo:${orgId} with TTL 600s.
3. Web: PUTs the file directly to R2 with the presigned URL.
4. Web: POST /:id/logo/confirm. Server verifies the Redis blob and r2.objectExists; UPDATEs logo_url = orgs/${orgId}/logo; invalidates cached presigned read URL; deletes the Redis blob.

G4 — Complete onboarding

1. POST /organizations/:id/onboarding-complete with optional {classTypeName, defaultDurationMin, defaultCapacity, inviteEmails}.
2. If classTypeName: find the org’s first program; insert a class type under it.
3. If inviteEmails: loop and call MembershipsService.createInvitation for each.
4. Send welcome email via the welcome template (apps/api/src/notifications/templates/welcome.ts). Pulls owner name from Clerk.
5. Returns { classTypeCreated, invitationsSent, emailSent }.

Edge cases & error states

Side effects

Permissions