unsupervised-scheduler/docs/features/group-classes.md

Feature: Group Classes

Overview

Students enrol in a group class — an offering of kind group_class — as a commitment for the year. Enrolment is capacity-enforced and billed full-term upfront. Registration reuses the same flow as private lessons (intake questions + policy acceptance + payment).

A group class can be marked invite-only (us_offerings.access_mode = invite_only, see offerings.md). Invite-only classes are hidden from the public catalog — they never appear in the student booking/group-class list — and can only be enrolled in by students the instructor has let in. See Invite-only access below.

Data Model — {prefix}us_group_enrollments

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
offering_id	BIGINT UNSIGNED	FK → us_offerings.id (kind = group_class)
student_id	BIGINT UNSIGNED	WordPress user ID
instructor_id	BIGINT UNSIGNED	WordPress user ID (denormalised from the offering)
status	VARCHAR(20)	active / cancelled / completed
payment_id	BIGINT UNSIGNED	Nullable FK → us_payments.id
enrolled_at	DATETIME	Insertion time

Class Dates

A group class offering carries term_start/term_end (see offerings.md): one-off classes end the day they start; weekly classes run a set number of sessions. The class card on the enrolment page shows the date or date range with the session count.

Enrolment Flow

The class list is loaded together with the student's own enrolments (GET /enrollments); a class the student already has an active enrolment in shows "You are enrolled in this class." instead of the Enrol button (the server would reject the duplicate with 409 already_enrolled regardless — a cancelled enrolment does not block re-enrolling).

1. Student opens a group class from the offering catalog.
2. Student answers the offering's questions (GET /offerings/{id}/questions).
3. Student accepts the current published policy versions (GET /policies) — required to continue.
4. Full-term payment is taken per the student's billing method (card by default; pending for e-transfer; skipped for comp). See payments.md.
5. POST /enrollments creates the enrolment (status = active), records answers and policy acceptances, and links the payment — but only if the offering's capacity has not been reached.
6. On successful payment (or comp) a receipt is emailed.

Capacity is enforced at enrolment time by counting active rows for the offering; a class at capacity rejects further enrolments.

REST API

Method	Endpoint	Permission
GET	/wp-json/us-scheduler/v1/enrollments	Any logged-in user
POST	/wp-json/us-scheduler/v1/enrollments	book_lesson

POST /enrollments body: offering_id, answers[] (question_id → value), accepted_policy_version_ids[], and payment data (see payments.md). The response includes id, status, and payment — a {id, method, status} summary, or null when the class is free (the front end then skips the payment step).

GET /enrollments returns the caller's own enrolments, or all enrolments for the instructor's group classes if the caller has view_own_lessons on those offerings.

GET /offerings (the catalog that feeds the group-class list) returns public offerings plus any invite-only offerings the caller has an access grant for, so a granted student sees the private class alongside public ones. Ungranted students never receive it. Enrolling in an invite-only class requires a grant: POST /enrollments rejects an ungranted student with 403 invite_required, and a successful enrolment flips their grant from invited to enrolled.

Invite-only access

Access to an invite-only class is recorded in {prefix}us_group_access — a grant per person, separate from the enrolment itself. The instructor manages access from My Lessons → My Group Classes, which renders three controls under each invite-only class:

1. Add students directly — the selected registered students are enrolled immediately (status = active) with a pending payment at the class price (comp students are settled at once by PaymentService). No access grant is needed — this writes straight to us_group_enrollments + us_payments.
2. Make available — the selected registered students get an invited grant so the class appears in their own group-class list; they then self-enrol through the normal paid flow. Each is emailed a "you've been added" notice.
3. Invite by email — for an address with no account yet: a tokenised personal invite (us_invites, carrying offering_id) is created and the registration link emailed, alongside an invited grant keyed by email + invite_id. If the address already has a pending invite, the grant is attached to that invite and no second link is sent. An address that already has an account is treated as Make available instead.

When an email-invited person completes registration, RegistrationPage links their new account to the grant (GroupAccessRepository::linkStudentByEmail), so the invite-only class becomes enrollable for them — they choose whether to enrol.

Data Model — {prefix}us_group_access

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
offering_id	BIGINT UNSIGNED	FK → us_offerings.id (an invite-only group class)
student_id	BIGINT UNSIGNED	WordPress user ID; NULL until an email invitee registers
email	VARCHAR(191)	Email-invite grants only; used to link the account once it registers
invite_id	BIGINT UNSIGNED	FK → us_invites.id for email-invite grants; NULL otherwise
status	VARCHAR(20)	invited / enrolled / revoked
invited_by	BIGINT UNSIGNED	Instructor who granted access
created_at	DATETIME	Insertion time

Admin Interface

• Group Classes (view_all_lessons / studio admin): all active enrolments across instructors
• My Lessons → My Group Classes (view_own_lessons / instructor): the instructor's own group classes, each showing its active-enrolment count against capacity and a per-class roster of enrolled students with enrolment and payment status. Invite-only classes additionally list who has been invited but not yet enrolled and carry the add/make-available/invite-by-email controls (nonce-checked usc_action POSTs, scoped to the owning instructor)

Implementation

• Repository: Unsupervised\Schedular\GroupClass\EnrollmentRepository (countActiveForOffering/hasActiveEnrollment enforce capacity and prevent duplicates)
• Access grants: Unsupervised\Schedular\GroupClass\GroupAccess + GroupAccessRepository (hasGrant, findGrantedOfferingIds, markEnrolled, linkStudentByEmail)
• Model: Unsupervised\Schedular\GroupClass\Enrollment
• Admin controller: Unsupervised\Schedular\GroupClass\GroupClassController — renderPage (studio admin, view_all_lessons) and renderInstructorPage (instructor, view_own_lessons)
• REST endpoint: Unsupervised\Schedular\GroupClass\EnrollmentEndpoint
• Frontend: Unsupervised\Schedular\GroupClass\GroupClassPage ([us_group_classes] shortcode; offering="…" restricts it to a single class for embedding on a dedicated page — the block equivalent is the offeringId attribute)
• Reuses Registration\RegistrationGate (intake answers + booking-scoped policy acceptance, type enrollment)

Payment: a priced enrolment creates a payment via Payment\PaymentService (registration_type = enrollment) and links it as payment_id; unpriced enrolments return payment: null and skip the payment step. See payments.md for the card/e-transfer/comp flows.

Tests

• tests/Unit/GroupClass/GroupClassControllerTest.php (roster + add/make-available/invite actions)
• tests/Unit/GroupClass/EnrollmentTest.php
• tests/Unit/GroupClass/EnrollmentRepositoryTest.php
• tests/Unit/GroupClass/EnrollmentEndpointTest.php (invite-only gating)
• tests/Unit/GroupClass/GroupAccessTest.php
• tests/Unit/GroupClass/GroupAccessRepositoryTest.php
• tests/Unit/GroupClass/GroupClassPageTest.php
• tests/Unit/Offering/OfferingEndpointTest.php (catalog merges granted invite-only classes)