unsupervised-scheduler/docs/features/parent-guardian-accounts.md

Feature: Parent/Guardian Accounts

Overview

A parent or guardian registers once and manages lessons for one or more children, without each child needing their own login. The guardian signs in, picks which child a booking is for, and pays for all of them from one account.

A guardian may also be a student in their own right — they appear in their own "who is this for?" selector alongside their children, so a parent taking lessons next to their kids needs only the one account.

Vocabulary: "child" in the code, "student" in the UI

The interface says student and profile; the code says child and family. This is deliberate, not drift. Every identifier below — the us_guardian_links columns, GuardianService::createChild(), the children[] request parameters, the child_name form fields, the us-scheduler/family block name and the [us_family] shortcode — is a stable contract with the database, saved post content and existing installs, so renaming them would break sites for no user-visible gain. Only the strings a person reads were changed.

When adding to this feature, keep the split: internal names follow the data model, translatable strings follow the interface.

Core Decision: children are accountless WordPress users

Every student_id column in src/Schema.php (us_lessons, us_payments, us_credits, us_group_enrollments, us_question_answers, us_policy_acceptances, us_group_access) is a wp_users id, and booking, billing, credits, policies and registration answers all resolve it directly.

Rather than change what student_id means, a child is a real wp_users row with the us_student role, created without a usable login:

• no password (wp_generate_password() is used and discarded — nothing is ever emailed, so it cannot be guessed into a session),
• no real email address; a child gets a placeholder login on the RFC 2606 reserved .invalid TLD (us-child-<random>@child.invalid, see GuardianService::childEmail()) — a well-formed address that can never resolve, so nothing about a child's account can be emailed somewhere real,
• the us_child user meta flag set to 1, which Guardian\ChildLoginGate uses to block authentication outright.

Consequences:

• us_lessons, us_group_enrollments, us_question_answers and us_group_access are unchanged — a child books like any other student.
• A child can be promoted to their own login later by setting a password and a real email and clearing us_child; no data migrates.
• A us_guardians link table maps guardian → child.

The alternative — a standalone us_students table decoupled from wp_users — was rejected for v1: it changes the meaning of student_id on seven tables and requires migrating every existing row.

Data Model — {prefix}us_guardians

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
guardian_id	BIGINT UNSIGNED	WordPress user ID of the parent/guardian
student_id	BIGINT UNSIGNED	WordPress user ID of the child
relationship	VARCHAR(50)	Free text shown in admin (e.g. "Parent", "Grandparent"); may be empty
created_at	DATETIME	Insertion time

UNIQUE KEY guardian_student (guardian_id, student_id) — the same pair can never be linked twice.

The table is a link table, not a child record: the child's name is their display_name on wp_users, and their birth year is the us_birth_year user meta. Keeping them on the user row means the admin student screens, get_users() ordering, and every existing student_id lookup keep working with no special-casing.

The legacy us_date_of_birth meta

This feature originally collected a full date of birth in us_date_of_birth. Nothing writes that key any more. It is handled entirely inside GuardianService:

• Read — birthYear() falls back to the year of the old date when us_birth_year is absent, so a child added before the change still shows one without a migration step.
• Write — setBirthYear() deletes us_date_of_birth on every save, including a save that clears the year. Without that the fallback would resurrect the old date on the next read and the year could never be cleared.

The upshot is a lazy migration: a child's full date survives until their record is next edited, then goes for good. There is no bulk purge — a site that wants the remaining old dates gone should delete the us_date_of_birth meta directly.

v1 is deliberately one guardian per child: GuardianRepository::insert() refuses to link a child that already has a guardian. The unique key and the guardian-side lookups already support many-to-many, so adding a second guardian (separated parents) later is an insert, not a migration.

Schema changes to existing tables

Table	Change	Why
us_payments	payer_id BIGINT UNSIGNED NOT NULL DEFAULT 0 + KEY payer_id	Who owes the money, when that is not the student
us_credits	payer_id BIGINT UNSIGNED NOT NULL DEFAULT 0 + KEY payer_id	Which account holds the balance
us_policy_acceptances	accepted_by BIGINT UNSIGNED NOT NULL DEFAULT 0	Who actually clicked, when that is not the student

All three default to 0, read back as "same as student_id" (see Payment::payerOrStudent(), Credit::payerOrStudent(), PolicyAcceptance::acceptorOrStudent()), so an existing row keeps its current meaning whatever happens — a pre-guardian payment is still owed by, and was still accepted by, the student it names.

The installer additionally backfills them (PaymentRepository::backfillPayerIds(), CreditRepository::backfillPayerIds(), AcceptanceRepository::backfillAcceptedBy(), run from Installer::migrateData()), because the balance lookups key on payer_id directly and an indexed WHERE payer_id = 5 would not see a legacy row still holding 0. The backfill is idempotent — it only touches rows still at 0 — and the payerOrStudent() fallbacks remain as the belt to its braces.

Billing: the guardian is the payer, the child is the subject

• us_payments.student_id keeps naming the child the lesson was for, so per-child payment reporting is unchanged.
• us_payments.payer_id names the guardian who owes it. Payment notices, receipts and the Stripe intent all resolve the payer.
• us_credits.payer_id is where a family balance lives. A credit from one child's cancelled lesson is held by the guardian and can settle a sibling's charge; CreditRepository::availableBalance() and consume() operate on the payer.
• The billing-method override (comp / card / etransfer, user meta read by BillingMethodResolver) resolves against the payer, so comping a family is one setting on the guardian rather than one per child.

PaymentService::createForRegistration() takes the payer id alongside the student id; BookingEndpoint and ScheduledBillingRunner both pass GuardianService::payerFor( $studentId ) — the child's guardian when they have one, otherwise the student themselves.

Family discounts are out of scope for v1 but are not designed out: with the payer on both the payment and the credit ledger, a discount rule has a family to apply to.

Registration

A "I'm registering as a parent or guardian" checkbox on the existing [us_student_register] form (all three signup paths — personal invite, group link, self-approval) reveals a repeatable child block. Ticking it requires at least one child name.

Per child the form collects:

• Name (required)
• Birth year (required, us_birth_year meta) — a four-digit year between 1900 and the current year. GuardianService::normaliseBirthYear() is the one definition of what counts, shared by the signup form's up-front validation and by createChild()/updateChild() themselves, so a bad year is refused rather than quietly discarded and a typo cannot leave a nonsense age on the record.
• Every account-scope registration question (Registration\Question, SCOPE_ACCOUNT) — asked once per child, not once per guardian, because in practice they describe the student (instrument, level, school). The guardian answers them on the child's behalf; the answer row's student_id is the child.

Name and birth year are marked required in the labels the same way a required question is, but the signup form cannot lean on the browser to enforce them: the child blocks are hidden until the parent/guardian box is ticked, and a required field inside a hidden container makes the form unsubmittable with no control the user can reach to fix. register.js therefore puts required on and takes it off along with the block itself ([data-us-child-required]), and the server checks regardless — which is what makes the rule hold with JavaScript off. The profile screen has no such problem: its forms are always visible, so the attribute is static there.

Order of operations in RegistrationPage::handleSubmit():

1. Validate the guardian's own fields (email, password, policies).
2. Validate every child block — a missing name, a missing or unusable birth year, or a missing required per-child answer fails the whole submission before any user is created, so a half-registered family is never left behind. An entirely empty block is dropped instead, because the form always renders one spare for "add another"; a block with anything at all typed into it is kept and reported on, rather than silently discarding what the guardian entered.
3. Create the guardian user.
4. For each child: create the accountless user, link it, record its answers, and record the signup policy acceptances against the child with accepted_by = <guardian>.
5. Roll back — every child user created so far is deleted and the guardian user with them — if any child creation fails, so a partial family never persists.

A guardian who does not tick the box registers exactly as before; nothing about the single-student flow changes.

Policy acceptance

us_policy_acceptances records one row per child for each signup-scoped policy, with:

• student_id = the child (who the policy binds),
• accepted_by = the guardian (who actually agreed),
• registration_type = 'account', registration_id = the child's user ID.

The guardian also gets their own acceptance row (student_id = accepted_by = guardian) whether or not they book for themselves — they agreed to the terms as an account holder. This is the legally meaningful record: "guardian X accepted policy version N on behalf of child Y at time T from IP Z".

Booking-scope policies are accepted at booking time by whoever is signed in; BookingEndpoint passes the same accepted_by when a guardian books for a child.

Managing children

[us_family] (block: Profile) renders the guardian's manage-children screen: list the children, add one, edit a name/birth year, remove one.

• Add creates another accountless child user and links it. Account-scope questions are asked here too, so a child added later carries the same information as one added at signup.
• Edit updates display_name and us_birth_year.
• Remove unlinks the child and deletes the child user, but only when the child has no lessons and no enrolments — a child with history is refused, so removing one can never orphan a lesson, payment or credit (GuardianService::removeChild()). The guardian is told to contact the studio instead.

Submissions are processed on template_redirect (like registration) and post/redirect/get back to the page, so a refresh cannot resubmit.

Booking

GET /bookings returns the lessons of the signed-in user and of every child they are guardian for, each row carrying student_id and student_name so the list can be grouped by child.

POST /bookings takes an optional student_id:

• absent or 0 → the current user books for themselves (unchanged),
• a child's id → the endpoint verifies with GuardianService::canActFor() that the current user is that child's guardian, and returns 403 forbidden when they are not. This is the authorisation boundary of the feature: without it any student could book, and bill, against any user id they cared to send.

The booking form gains a "Who is this for?" <select>, rendered only when the account has more than one person on it, so a single-student account's form is unchanged.

Children are listed first and the account holder last (GuardianService::bookableStudents()). The order is the whole point: a guardian's normal case is booking for a child, so the default selection — the one a parent gets by not touching the picker at all — is a child, never themselves. Booking for the wrong child is a correctable inconvenience; silently billing a parent's account for a lesson meant for their kid is the error worth designing out. The guardian is still offered, last, so a parent taking lessons alongside their children can book for themselves.

The list is rendered server-side into data-students on the page wrapper and read by assets/js/guardian.js, which both the booking and group-class scripts share.

POST /bookings/<id>/cancel accepts a cancellation from the lesson's student or their guardian, subject to the same cancellation cutoff.

Group classes

POST /enrollments carries the same optional student_id and the same canActFor() check, GET /enrollments covers the household, and POST /enrollments/<id>/withdraw accepts the guardian — group enrolment is the other place a family books and pays, so it gets the identical treatment rather than being left as a single-student-only path.

Admin

• Students list gains a Profile column: a child links to its guardian's detail screen, a guardian lists its children as links. Children are listed alongside every other student rather than nested, so nothing about finding a student changes.
• Student detail gains a Profile panel — the guardian (for a child) or the children (for a guardian), each a link to the other's screen — and the credit balance shown is the payer's balance, labelled with whose it is, so an admin looking at a child sees the family balance that will actually settle their charges rather than an empty per-child one.
• Registration answers and policy acceptances on a child's screen show "accepted by " where the acceptor differs from the student.

Creating or attaching a child from wp-admin is out of scope for v1; a studio admin adds children through the guardian's own family screen or asks the guardian to.

Capabilities

No new capability. A child user holds the us_student role (so every existing student_id capability check keeps working) but can never sign in (Guardian\ChildLoginGate blocks wp_authenticate_user and forces user_has_cap to withhold book_lesson from a child), so the role grants them nothing in practice. Guardians act for children through GuardianService::canActFor(), checked at every REST and form boundary, rather than through a capability.

Instructor view

Lesson lists show the student's name. Where that student is a child, the instructor also sees the guardian's name and email — the contact they actually need — via GuardianService::contactFor().

Implementation

• Models: Unsupervised\Schedular\Guardian\GuardianLink
• Repository: Unsupervised\Schedular\Guardian\GuardianRepository
• Service: Unsupervised\Schedular\Guardian\GuardianService (child creation, canActFor(), payerFor(), contactFor(), removal rules)
• Login block: Unsupervised\Schedular\Guardian\ChildLoginGate
• Frontend: Unsupervised\Schedular\Guardian\FamilyPage ([us_family])
• Shared question field: Unsupervised\Schedular\Registration\QuestionField (one question rendered under a caller-supplied input name, so the same question can appear once per child without colliding)
• Front-end script: assets/js/guardian.js (the shared picker), assets/js/register.js (guardian toggle + "add another child")
• Extended: Auth\RegistrationPage (guardian checkbox, child blocks, per-child answers/acceptances, rollback), Booking\BookingEndpoint and GroupClass\EnrollmentEndpoint (student_id param + guardian authorisation, household listings), Booking\BookingPage, GroupClass\GroupClassPage, Payment\PaymentService, Payment\PaymentRepository, Payment\CreditRepository, Payment\ScheduledBillingRunner (one notice per payer), Policy\AcceptanceRepository, Registration\RegistrationGate, Auth\StudentController, Installer (backfills)
• Schema: us_guardians; us_payments.payer_id; us_credits.payer_id; us_policy_acceptances.accepted_by

Tests

• tests/Unit/Guardian/GuardianLinkTest.php
• tests/Unit/Guardian/GuardianRepositoryTest.php
• tests/Unit/Guardian/GuardianServiceTest.php
• tests/Unit/Guardian/ChildLoginGateTest.php
• tests/Unit/Guardian/FamilyPageTest.php
• tests/Unit/Auth/RegistrationPageTest.php (guardian signup path)
• tests/Unit/Booking/BookingEndpointTest.php and tests/Unit/GroupClass/EnrollmentEndpointTest.php (booking/enrolling for a child, and the 403 when the caller is not the guardian)
• tests/Unit/Booking/BookingPageTest.php (children lead the embedded list)
• tests/Unit/Payment/PaymentServiceTest.php, CreditRepositoryTest.php, ScheduledBillingRunnerTest.php (payer, family balance, one notice)

Related

account-registration.md, lesson-booking.md, payments.md, credits.md, group-classes.md, student-administration.md, policies.md, registration-questions.md.