unsupervised-scheduler/docs/features/user-roles.md

Feature: User Roles

Overview

Three custom WordPress user roles control access to all scheduling features: a studio admin who runs the business, instructors who teach, and students who book.

Roles

Studio Admin (us_studio_admin)

Runs the studio. Logs in via standard wp-admin. Can:

• Create instructor accounts and set/revoke each instructor's capabilities
• Manage offerings, intake questions, and policies
• Configure Stripe credentials and per-student billing overrides (card / e-transfer / comp)
• View the studio-wide scheduler (all upcoming lessons across instructors)
• View the all-instructor payments report and export it

Capabilities: read, manage_instructors, manage_offerings, manage_questions, manage_policies, manage_billing, view_all_lessons, view_all_payments, export_payments

Any WordPress administrator (manage_options) implicitly holds every studio-admin capability above and the instructor capabilities (notably manage_availability), so a single-instructor studio owner can run the business and teach — managing their own availability and lessons — from one account, without being assigned the us_studio_admin or us_instructor role. This is applied dynamically via the user_has_cap filter (RoleManager::grantStudioCapsToAdministrators()) — it persists nothing and is removed when the plugin is deactivated. The us_studio_admin role exists for non-administrator staff who manage the studio.

Both grants can be turned off independently on the Access admin page (AccessSettings, options us_admin_grant_studio / us_admin_grant_instructor, both default on) — for example, when dedicated us_studio_admin or us_instructor accounts run the studio and administrators should not appear as studio staff. That page is gated on the core manage_options capability (which the plugin never grants or revokes), so an administrator can always reach it to re-enable a grant; disabling one can never lock them out.

Instructor (us_instructor)

Created by the studio admin. Logs in via standard wp-admin. Can:

• Manage their own availability slots (add/delete), including weekly-recurring windows
• Manage their own offerings and intake questions
• View their upcoming confirmed/pending lessons and group enrolments
• View and export their own payments

Capabilities: read, manage_availability, manage_offerings, manage_questions, view_own_lessons, view_own_payments, export_payments

Student (us_student)

Logs in via the front-end [us_student_login] shortcode. Can:

• Browse available lesson slots and offerings from all instructors
• Book a private lesson (single or weekly) and enrol in group classes

Capabilities: read, book_lesson, view_own_lessons

Capability Matrix

Capability	Studio Admin	Instructor	Student	Used by
manage_instructors	✓			Instructor management
manage_availability		✓		Availability
manage_offerings	✓	✓ (own)		Offerings
manage_questions	✓	✓ (own)		Registration questions
manage_policies	✓			Policies
manage_billing	✓			Payments (Stripe + overrides)
book_lesson			✓	Lesson booking / enrolment
view_all_lessons	✓			Scheduler dashboard
view_own_lessons		✓	✓	Lesson + group views
view_own_payments		✓		Payment reporting
view_all_payments	✓			Payment reporting
export_payments	✓	✓ (own)		Payment reporting export

Instructor Management

The studio admin gets an Instructors admin page (gated by manage_instructors) to add an instructor — creating the WP user with the us_instructor role and emailing them a set-password link — and to toggle that instructor's per-capability access. The managed capabilities are manage_offerings, manage_questions, view_own_payments, and export_payments; manage_availability and view_own_lessons are core to every instructor and are not managed here. The us_instructor role grants the managed capabilities by default, and the page stores per-user overrides on top of the role.

A studio admin cannot grant a capability it does not itself hold: only capabilities the acting user has (checked via current_user_can(), so an administrator's dynamic grant counts) are offered as toggles, and on creation any managed capability the admin lacks is denied on the new instructor so they never exceed the creator. The grantable/assignment rules live in the pure, unit-tested Auth\InstructorCapabilities; InstructorController applies the result to the WP_User.

Implementation

• Class: Unsupervised\Schedular\Auth\RoleManager
• Instructor management controller: Unsupervised\Schedular\Auth\InstructorController
• Roles are created on plugins_loaded → init and on plugin activation via Installer.
• Permissions are checked with current_user_can() against the capability string, not the role name.

Tests

• tests/Unit/Auth/RoleManagerTest.php
• tests/Unit/Auth/InstructorCapabilitiesTest.php