Scheduling & Bookings — Behavior

State machines

Class session (class_sessions.status, enum publish_status)

archived is in the enum but not used for class sessions (it’s the course terminal state).

Booking (bookings.status, enum booking_status)

Invariants

• One active booking per (session, member) — DB-level unique(class_session_id, membership_id) on bookings. The service additionally guards by status: existing booking in ('confirmed','waitlisted') raises BadRequestException('Already booked for this session').
• Capacity is hard — booking inserts only happen when count(confirmed) < session.capacity (or capacity is null = unlimited). waitlisted only when count(waitlisted) < session.waitlistCapacity. Check + insert run inside one SERIALIZABLE transaction.
• Org isolation — every session read joins classType → program → organizationId. Writes use a subquery to constrain the UPDATE: inArray(classSessions.id, orgScopedSessionIds) (see ClassSessionsService.update/publish/unpublish/cancel/checkIn).
• A draft cannot be booked — book() throws BadRequestException('Session is not open for booking') unless session.status === 'published'.
• Cancelled sessions cancel all bookings — cancel() runs the status update and a bulk bookings update in a single transaction.
• Unpublishing requires no active bookings — unpublish() throws BadRequestException('Cannot unpublish a session that has active bookings') if getBookingCounts returns > 0.
• Bulk-delete is soft-delete — sets deletedAt. Active bookings get cancelled. Audit row created with batchId, sessionIds, filter payload.
• Bulk-publish forces status filter to draft — caller’s filter status is overwritten regardless of input. Defense-in-depth.
• Plan-credit consistency — credit deduction (deductCreditAtomic) and refund (refundCreditAtomic) run inside the same booking transaction. Unlimited subs (plan.type='subscription' AND classCredits IS NULL) skip both. Course-type subs are excluded entirely from resolveSubscription*.
• Late cancel never refunds credit — even if allowLateCancellation=true, shouldRefund = wasConfirmed && !isLateCancellation && subscriptionId != null.
• Coach role validation — classSession.coachMembershipId only accepts memberships with role ∈ {owner, admin, coach} and status='active'.

Golden paths

Owner: weekly schedule

1. GET /organizations/:orgId/class-types to see programs/class types.
2. POST /organizations/:orgId/sessions for each slot (default status='draft'). Pre-validated against classType + location + coach membership.
3. Optionally PUT /sessions/:id/workouts to attach pre-built workouts, or POST /sessions/:id/workouts/inline to create one in place.
4. POST /sessions/:id/publish (or POST /sessions/bulk-publish with a filter for a whole week of drafts).
5. Members now see the session inside their schedule and may book.

Coach: daily class

1. GET /organizations/:orgId/sessions?weekStart=… for the assigned slots.
2. Open session, see roster via GET /sessions/:id/bookings.
3. Generate display QR via POST /sessions/:id/display-url (10-minute signed URL embedding org+session+sig+exp).
4. Throughout class, POST /sessions/:id/check-in/:bookingId for any member who hasn’t self-checked-in.
5. Optionally POST /sessions/:id/workouts/inline to log what was actually trained that day.

Member: book + attend

1. GET /sessions?weekStart=… — receives sessions with bookingEligibility per session.
2. If eligibility.status='eligible' and the chosen plan is unblocked, POST /sessions/:id/book (server picks the single active sub automatically; passing subscriptionId explicitly for ambiguous multi-plan case).
3. Receives confirmed or waitlisted (depends on capacity). Push + email fire after commit.
4. T-30 minute reminder push lands (scheduled BullMQ job).
5. On arrival, scan QR or tap GPS check-in → POST /sessions/:id/self-checkin. selfCheckin validates: confirmed booking exists, check-in window open (isWithinCheckinWindow), QR signature valid OR GPS distance ≤ GPS_MAX_METERS.
6. Booking status → attended, checkedInAt, checkinMethod populated.

Member: cancel

1. DELETE /organizations/:orgId/sessions/:sessionId/book.
2. Service checks org.cancellationWindowHours against session.startsAt. If past deadline:
   • If allowLateCancellation=false → BadRequestException.
   • If allowLateCancellation=true → cancel proceeds, no credit refund.
3. Otherwise cancel proceeds, credit refunded (if booking had subscriptionId).
4. If the cancelled booking was confirmed, promoteFromWaitlist looks up the lowest waitlistPosition booking on the same session, flips it to confirmed, and fires the “you’re in” email.

Edge cases & error states

Side effects

Permissions matrix

isStaffRole returns true for owner|admin|coach — used for credit/quota bypass on booking but not for the booking RBAC check (members can still book).