Glossary

Domain terms used across the codebase. Alphabetical. Each entry links to the relevant code or feature doc when one exists.

Agent. The FitKit AI assistant (“Spotter”) — see Spotter. The word agent shows up in code (apps/api/src/ai/agent/, libs/db/src/lib/schema/agent.ts) because internally it’s modeled as a tool-using agent. Externally we call it Spotter.

Announcement. Org-wide broadcast posted to all members. Distinct from a Message (1:1) and a Feed item (member-generated activity). Schema: libs/db/src/lib/schema/announcements.ts.

Assignment / Workout assignment. A scheduled cell in a coach’s per-member grid pointing at a workout (or a rest day, or a free-text note). assignment_kind enum: workout | rest | note. Schema: libs/db/src/lib/schema/workouts.ts (workoutAssignments).

Audit log. Append-only audit_logs table capturing actor + action + resource. Currently captures select writes (e.g. admin tier changes); full coverage is FIT-20 — not yet implemented end-to-end. Schema: libs/db/src/lib/schema/admin.ts.

Booking. A member’s reservation in a Class Session. Statuses: confirmed | waitlisted | cancelled | no_show | attended. Schema: libs/db/src/lib/schema/scheduling.ts (bookings).

Bull-Board. The BullMQ admin UI mounted at the API. See apps/api/src/bull-board/. Used internally to inspect queues (push notifications, embeddings, imports, exports, recurring billing).

Cardcom. Israeli payment provider (one of several supported). Provider enum value: cardcom. Used for FitKit’s own platform billing (B2B) and as an option for organizations’ member billing.

Class Session. A specific scheduled instance — “Open Gym, Tuesday 18:00”. Has capacity, location, instructor. Lifecycle: draft → published → cancelled. Schema: libs/db/src/lib/schema/scheduling.ts (classSessions).

Class Type. The template a session is generated from — “Open Gym”, “CrossFit WOD”, “Pilates Mat”. Owns default duration, capacity, location, color. Schema: libs/db/src/lib/schema/scheduling.ts (classTypes).

Coach. Membership with role = 'coach'. Builds workouts, assigns programs, runs sessions, reviews forms. See personas.md.

Coaching grid. The week-by-member matrix view a coach uses to assign workouts. Backed by workoutAssignments rows.

Compliance form. A Form Template with kind = 'compliance' — e.g. liability waiver, health declaration. Produces signed PDFs stored in the compliance R2 bucket (FIT-158). 7+ year retention per Israeli Sports Promotion Law.

Course. A purchasable program (plan_type = 'course'). One-time payment, lifetime access, sequential or open curriculum. Schema: libs/db/src/lib/schema/courses.ts.

Course entitlement. Per-buyer access record. Lifecycle: pending → active → revoked. Schema: same file.

Cycle. Used loosely in two senses. (1) Billing cycle: a recurring period of a Subscription — see subscriptionStatus and the billing-retry scheduler. (2) Program cycle: a contiguous block of a program template applied to a member. The codebase doesn’t use a dedicated cycle table — both senses are expressed via timestamps on the parent entity.

Daily programming. The coach’s daily-published WOD surface. Per-org, per-day, optional per-class-type. Schema: libs/db/src/lib/schema/scheduling.ts includes the daily-programming relations; module at apps/api/src/daily-programming/.

Delivery mode. How a Program reaches members: feed | schedule | coaching | course. Drives which UI and assignment mechanics apply.

Drop-in. A plan_type = 'drop_in' plan — single-session purchase. Doesn’t auto-renew.

Feed item. Member-generated activity (workout logged, PR achieved, class attended). Powers community surfaces. Schema: libs/db/src/lib/schema/community.ts.

Form Instance. A specific filled-out copy of a Form Template for a specific member. Carries answers + (for compliance) signed-PDF URL + signing token. Lifecycles diverge by kind: compliance is draft → pending → signed → archived; check-in is scheduled → sent → answered → reviewed. Schema: libs/db/src/lib/schema/forms.ts.

Form Template. The org-owned definition of a form (questions, layout, validation). form_kind: compliance | check_in. Schema: same file.

Horaot keva. Israeli standing-order direct-debit. A supported recurring-payment method for member subscriptions.

Invitation. A pending Membership sent to an email. Lifecycle: pending → accepted | revoked | expired. Accepted invitations are auto-picked-up via the Clerk webhook on user creation. Schema: libs/db/src/lib/schema/invitations.ts.

Lead. A prospect captured from the minisite, a QR scan, a manual entry, etc. Lifecycle: new → contacted → trial_booked → converted | lost. Has an associated Task for follow-up. Schema: libs/db/src/lib/schema/leads.ts.

Membership. The join row between a User and an Organization, carrying role, status, and paymentStatus. A user has one membership per org they belong to. Schema: libs/db/src/lib/schema/memberships.ts. Distinct from a Plan (the SKU) and a Subscription (the recurring contract).

Membership Type / Plan. Used interchangeably in some product docs, but in code they’re distinct. A Plan is the SKU; a Membership is the user↔org join. “Plan tier” or “plan type” refers to the SKU (plan_type: subscription | class_pack | drop_in | course).

Metric definition / Metric set. A definition of a measurable quantity (1RM Squat, 5K time) and a grouping for coaching templates. Schema: libs/db/src/lib/schema/metric-sets.ts.

Minisite. Public, per-org marketing page on a FitKit subdomain or custom domain. Editor lives in the dashboard; renderer is apps/minisites/ (Astro). Schema: libs/db/src/lib/schema/minisites.ts.

Morning (formerly GreenInvoice). Israeli invoicing + payments provider. Auth endpoint is on api.morning.{co,sandbox.dev}; business API is still on *.greeninvoice.co.il.

Onboarding. The new-org or new-user first-run flow. Owners step through org-name → legal acceptance → first members. Module: apps/web/src/components/onboarding/.

Organization. A studio / gym / coach business. Multi-tenant boundary — every domain table has organization_id. Schema: libs/db/src/lib/schema/organizations.ts. organization_type: physical | online | hybrid.

Plan. A purchasable SKU configured by the studio owner. Types: subscription | class_pack | drop_in | course. Schema: libs/db/src/lib/schema/payments.ts (plans).

Platform Admin. A FitKit-employee user with cross-org tools (not a membership role).

Platform tier. The org’s FitKit subscription tier: lite | pro | elite. Drives feature-gating via PlatformTierGuard + @RequiresFeature(...). Schema enum: libs/db/src/lib/schema/enums.ts: platformTier.

Program. A coach’s structured delivery of training. Has a delivery_mode and enrolled members. Distinct from a Program Template (reusable definition). Schema: libs/db/src/lib/schema/scheduling.ts (programs).

Program Template. A reusable multi-week program structure (FIT-74). Apply to memberships, generate workout assignments. Excluded from delivery_mode = 'course'. Schema: libs/db/src/lib/schema/program-templates.ts.

Router (Spotter). The internal LLM call that decides which Spotter tool to invoke for a user turn. Implementation: apps/api/src/ai/agent/agent.orchestrator.ts.

Signing (form signing). The compliance-form mechanic: server issues a single-use signed link (7-day TTL — see SIGNING_TOKEN_TTL_MS in apps/api/src/forms/forms.service.ts); member opens it, types their name (or draws a signature), server renders + uploads a signed PDF.

Spotter. The user-facing brand name for the AI assistant. Internally called “agent” in code. Phase 1 = coach-only. See features/spotter-agent/ and personas.md.

Studio / Coach / Trainer. Loose interchangeable terms for the operator-side personas. The memberships.role enum is the authoritative classification: owner | admin | coach | member. Studio is colloquial for an org with organization_type = 'physical'.

Subscription. The recurring contract between a member and a plan, with billing lifecycle (pending | active | past_due | cancelled | paused | debt). Schema: libs/db/src/lib/schema/payments.ts (subscriptions). Distinct from a Plan (the SKU) and a Membership (the org join).

Task. A to-do for the operator — lead follow-up, manual refund, cancellation review, etc. Auto-created by triggers (task_trigger_type enum). Schema: libs/db/src/lib/schema/tasks.ts.

Tool (Spotter). A typed capability the Spotter agent can invoke (e.g. “create workout”, “fetch member history”). Definitions: apps/api/src/ai/agent/tools/. Each tool has a Zod input/output schema and is registered via the tool-registry.service.ts.

Trainer. Synonym for Coach in operator-side conversation. The code uses coach.

Workout. A specific training session definition (movements, scoring, structure). Versioned: snapshots are taken when a workout is assigned so later edits don’t mutate history. Schema: libs/db/src/lib/schema/workouts.ts.

WOD. “Workout of the Day” — colloquial CrossFit term, used interchangeably with Workout in the daily programming surface.