Scheduling & Bookings — Code Map

API

Module — class sessions (apps/api/src/class-sessions/)

Routes (prefix organizations/:orgId/sessions)

Module — bookings (apps/api/src/bookings/)

Routes

Web

Routes

Hooks / API helpers

• useApi (client) and serverFetch (server) — Clerk bearer attached automatically. See apps/web/src/hooks/use-api.ts, apps/web/src/lib/api.ts.
• apps/web/src/components/overview/schedule/* — calendar grid (weekly-calendar.tsx), create sheet (create-session-sheet.tsx), detail/edit sheet (session-detail-sheet.tsx), shared fields incl. the space picker (session-fields.tsx), bulk-delete sheet, timetable menu. Space required when flag spaces is on and the org has ≥2 active spaces; owner/admin override dialog on the space 409s (space-override-dialog.tsx: useSpaceOverride + SpaceOverrideDialog, used by the create and detail sheets).
• apps/web/src/components/member/schedule/session-detail-drawer.tsx — member booking drawer. Always sends the plan it shows; on 409 plan_selection_required its plan picker lists the body’s plans (first preselected) and booking from it retries with the chosen subscriptionId. Waitlist offer, rank line and cancel button/policy text come from the server fields through session-booking-state.ts (isWaitlistOpen, resolveCancellationState, isLateCancellationState).
• apps/web/src/components/overview/schedule/session-detail-sheet.tsx — staff roster: waitlist ordered and numbered by waitlistRank; cancelled rows carry a cancellationReason badge.
• Drag layer schedule-drag.tsx (TKN-478): ScheduleDragProvider (the DnD context, used by SpaceSections and around the flat Expanded/Condensed views), resolveDrop (same day in another hall’s section → move; another day → copy with that section’s hall and, in the hour grid, the slot’s time), ScheduleDropZone (a condensed day column, or one hour slot of expanded-week-grid.tsx), ScheduleDraggable, useCopyToDay and the “Copy to day…” dialog. use-session-copy.ts posts the copy, runs the override dialog, opens the copy, toasts Undo (DELETE) and captures schedule_session_copied. SessionRowMenu (space-sections.tsx) is the condensed row’s menu: “Move to space” in a section, “Copy to day…” while copying is on.

DB tables involved

Shared schemas

• libs/shared/src/lib/schemas/scheduling.schema.ts — Zod schemas for session response, booking response, bulk filter, eligibility (BookingEligibility, BookingPlanEntry, BookingBlockReason), the plan_selection_required body’s entries (PlanSelectionCandidate), and spaces (spaceOverrideSchema, spaceConflictErrorSchema, spaceCapacityErrorSchema).
• libs/shared/src/lib/constants/scheduling-error-codes.ts — SchedulingErrorCodes (space_conflict, space_capacity_exceeded).
• libs/shared/src/lib/constants/payment-error-codes.ts — the booking gate’s codes: booking_blocked_debt, plan_required_to_book, plan_not_started, plan_selection_required.
• libs/shared/src/lib/analytics/booking-events.ts — BOOKING_PLAN_SELECTION_REQUIRED (booking_plan_selection_required); waitlist: WAITLIST_PROMOTION_SKIPPED, WAITLIST_PROMOTED, WAITLIST_REMOVED_ELSEWHERE, WAITLIST_EXPIRED, WAITLIST_HOLD_LIMIT_REFUSED, BOOKING_GRACE_CANCEL, SEATS_FILLED_FROM_WAITLIST.
• libs/shared/src/lib/constants/booking.ts — WAITLIST_PROMOTION_CUTOFF_MINUTES (15), WAITLIST_PROMOTION_GRACE_MINUTES (10), BOOKING_CANCELLATION_REASONS, MY_CANCELLATION_STATES.
• scheduling.schema.ts also carries waitlistPromotionSkipReasonValues (evaluator reasons + subscription_inactive) and the response fields waitlistOpen, waitlistCount, myWaitlistRank, myCancellationState, myFreeCancelUntil, myPromotedAt (session) and promotedAt, cancellationReason, waitlistRank (booking).
• libs/shared/src/lib/schemas/day-of-week.ts — dayOfWeekValues array used by bulk filter.
• isStaffRole helper in @taikan/shared — single source of truth for staff vs member.

Tests

Space context (TKN-460)

• GET /sessions and GET /sessions/upcoming-today (class-sessions controller) and the booking attendance reads (/bookings/attendance-trend, /analytics/attendance/{summary,daily}) take an optional spaceId, resolved by SpaceScopeService and applied as class_sessions.location_id = :space; a session without a space matches only “every space” until S4. BookingsService.getAttendanceSummary drops deleted bookings in the join (the old unparenthesised OR let every org through). The web Today panel reads both session endpoints through useScopedApiQuery. See space-context/code-map.md.

Booking policy rules (TKN-447/448)

Spotter tools (booking rules and entry quotas)

apps/api/src/ai/agent/tools/leaves/booking-policy.tools.ts (BookingPolicyAgentTools) calls the services above, so permissions, the save checks and the refusal bodies are the dashboard’s. No tool reads a feature flag; the services enforce what they enforce. Reads are served over MCP too; writes wait for the approval card in Spotter and are never served over MCP.

• Rule and quota inputs are flat shapes the model can read cheaply (libs/shared/src/lib/agent-schemas/booking-policy.ts), each held to the HTTP body schema it stands for, so an invalid one is refused as invalid_input before any service runs.
• BookingPolicyService.names labels the ids an answer carries (halls, class types, programs, plans, rules) in one query per kind.
• The refusal table Spotter answers with (meaning and next step per code, space_conflict and space_capacity_exceeded included) is BOOKING_RULES_PROMPT in apps/api/src/ai/agent/context-builder.service.ts; its spec fails when a refusal code has no row.
• Tests: booking-policy.tools.unit.spec.ts (role scope, validation, refusal passthrough, approval, MCP exposure) over booking-policy.tools.driver.ts (real registry and runner, stubbed services).