Organizations

What is this

An organization is Taikan’s tenant unit — a single studio, gym, coach business, or chain. Every domain row (sessions, bookings, members, leads, plans, locations, programs, workouts, payments) is tied back to exactly one organizations.id. The org row holds branding (logoUrl, name, slug, description), localization (timezone, currency), commercial state (platformTier), and a few cross-cutting policies (cancellationWindowHours, allowLateCancellation).

Organizations are also mirrored into Clerk as Clerk organizations (clerk_organization_id) — Taikan creates one in Clerk on POST /organizations so Clerk’s org-membership UI (org switcher, invitations) is wired up alongside Taikan’s memberships rows.

Who uses it

Persona impact

• Owner-only: completeOnboarding (only the owner can finalize the org setup flow). Suspending or cancelling the last owner membership is blocked.
• Logo uploads are two-step: presigned R2 upload URL + confirm. Lite tier has a max upload size of 2 MB and limited MIME types (image/jpeg, image/png, image/webp). 10-minute upload window.
• Slug auto-generated on create from name + 6-char random suffix; unique. Currently no slug-edit endpoint.

High-level capabilities

1. Create org — POST /organizations. Also creates the matching Clerk organization (with createdBy=clerkId so the caller is admin in Clerk too). Inserts an owner-role memberships row.
2. List my orgs — GET /organizations — every org where the caller has an active membership.
3. Get / update — owner/admin only.
4. Logo flow — POST /:id/logo/upload-url returns a presigned R2 PUT URL + R2 key; POST /:id/logo/confirm validates that the object exists and persists the key to organizations.logo_url.
5. Onboarding complete — POST /:id/onboarding-complete (owner only). Optionally creates a class type, batch-invites members, and sends a templated welcome email.
6. Booking policy — cancellationWindowHours + allowLateCancellation read by the booking cancel flow, registrationOpensBeforeMinutes + registrationClosesBeforeMinutes (nullable lead times) read by the booking flow to bound when members may register, and the billing settings billingGraceDays (days to pay before a plan in debt is cancelled for non-payment, 0–30) / planRequiredToBook read by the payments debt rules, the subscription lifecycle and the booking billing gate (see Billing grace setting).
7. Tier — platformTier enum (lite|pro|elite) drives feature gates via @taikan/shared.checkTierLimit and @RequiresFeature decorators.
8. Minisite — public marketing site for the org. Owned via minisite_content table (FK from organizations). See apps/api/src/organizations/minisites.controller.ts.
9. Branding workspace — flag-gated Brand / Website / Mobile app workspace. Shared identity and bounded color/background defaults live in the organization appearance authority; channel-specific content and releases remain independently reviewed and published.

Relationship to other features

• users-auth — org creation calls Clerk; clerk_organization_id stored.
• memberships — org → members many-to-many through this table.
• onboarding — the setup sheet’s submit calls POST /organizations, then POST /legal/consents, then POST /:id/onboarding-complete.
• scheduling-bookings — cancellationWindowHours + allowLateCancellation read by the booking cancel path. timezone used to format session times.
• locations — direct FK from locations.organization_id. Each row is a space (ADR-0024 D1).
• leads-crm — organization_leads.organization_id direct FK.
• Platform tiers / billing — platformTier controls maxSpaces, maxMembers, maxCoaches and feature flags (lead_management, etc.). See apps/api/src/platform-tiers/.
• minisites — inherits the published shared brand unless the website has an explicit logo/content override.

Multi-org membership & the active-org switcher

A Clerk user can hold memberships in any number of orgs (the memberships unique constraint is (user_id, organization_id)). The API never resolves a “current org” server-side — org identity is always an explicit :orgId path param validated by requireMembership, so any org the caller belongs to is reachable per-request. The active org is purely a client concept:

• Selection precedence (identical on web and mobile): the explicitly selected org if it still matches an active membership, else the highest-privilege active membership (owner > admin > coach > member).
• Web: selection persisted in the taikan_active_org cookie (apps/web/src/lib/active-org.ts), read by the protected layout / prefetchUserAndData on the server and by ActiveOrgProvider → useCurrentUser on the client. Switcher UI: OrgSwitcher (components/shared/org-switcher.tsx) wraps the org block in the dashboard sidebar and the member header; it renders only when the user has 2+ active memberships. Switching sets the cookie and hard-navigates to the target role’s home, which resets query cache, realtime, and analytics grouping.
• Mobile: selection persisted in AsyncStorage (src/lib/settings-store.ts activeOrgId), preloaded behind the splash and held in ActiveOrgProvider; OrgSwitcher (src/components/fk/org-switcher.tsx) makes the member-header org block tappable. Switching invalidates the whole React Query cache (all org-scoped keys embed the orgId). Cleared on sign-out.
• Second-org invitations: GET /users/me converts pending_invitation shells via acceptPendingInvitations even when the user already has an active membership elsewhere; createInvitation re-arms a cancelled/suspended membership row back to pending_invitation on re-invite.

Current status

Shipped. Areas with active churn:

• OrganizationsService.create only creates the org + owner membership. Starter programs are seeded by completeOnboarding: one per entry in the request’s deliveryModes (named from programNames[mode] or a per-locale default, skipped when the org already has a program of that mode), plus a default class type for a schedule program that has none. The onboarding setup sheet sends that request right after POST /organizations (see onboarding).
• Logo upload is R2-only; legacy logoUrl values that are full URLs (e.g. from Clerk imageUrl) are passed through. Relative keys starting with orgs/ get presigned for read.

Known gaps

• No “transfer ownership” endpoint. Updating an owner’s role to non-owner is guarded against if they’re the last owner.
• No org soft-delete path exposed in the controller. The schema has deleted_at, the service does not write it.
• Slug is auto-generated; no edit. If a name collision happens after slugification, the 6-char suffix makes it unique but the URL changes if the org is recreated.
• Currency is a plain varchar(3) — no validation against ISO 4217 codes at the API layer (TODO: verify whether Zod schema enforces this).