> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Session Scheduling — Administrator Guide

> Module: Practice Management (PM) Feature: PM-04 Group Session Scheduling Version: 1.0 Updated: 2026-02-19

**Module:** Practice Management (PM)\
**Feature:** PM-04 Group Session Scheduling\
**Version:** 1.0\
**Updated:** 2026-02-19

***

## Overview

This guide covers permission configuration, role assignments, capacity management, waitlist behavior, and data administration for the Group Session Scheduling feature (PM-04).

***

## Permission Key Reference

| Permission Key                | Constant                                  | Description                                   |
| ----------------------------- | ----------------------------------------- | --------------------------------------------- |
| `pm.group_definitions.view`   | `PM_PERMISSIONS.GROUP_DEFINITIONS_VIEW`   | View group definition list and detail pages   |
| `pm.group_definitions.create` | `PM_PERMISSIONS.GROUP_DEFINITIONS_CREATE` | Create new group definitions                  |
| `pm.group_definitions.edit`   | `PM_PERMISSIONS.GROUP_DEFINITIONS_EDIT`   | Edit existing group definitions               |
| `pm.group_definitions.delete` | `PM_PERMISSIONS.GROUP_DEFINITIONS_DELETE` | Soft-delete group definitions                 |
| `pm.group_schedule.view`      | `PM_PERMISSIONS.GROUP_SCHEDULE_VIEW`      | View schedule occurrences                     |
| `pm.group_schedule.create`    | `PM_PERMISSIONS.GROUP_SCHEDULE_CREATE`    | Create new session occurrences                |
| `pm.group_schedule.edit`      | `PM_PERMISSIONS.GROUP_SCHEDULE_EDIT`      | Edit session occurrences                      |
| `pm.group_schedule.delete`    | `PM_PERMISSIONS.GROUP_SCHEDULE_DELETE`    | Cancel session occurrences                    |
| `pm.group_enrollments.view`   | `PM_PERMISSIONS.GROUP_ENROLLMENTS_VIEW`   | View enrollment list and waitlist             |
| `pm.group_enrollments.create` | `PM_PERMISSIONS.GROUP_ENROLLMENTS_CREATE` | Enroll patients into groups                   |
| `pm.group_enrollments.edit`   | `PM_PERMISSIONS.GROUP_ENROLLMENTS_EDIT`   | Update enrollment status (disenroll, promote) |
| `pm.group_enrollments.delete` | `PM_PERMISSIONS.GROUP_ENROLLMENTS_DELETE` | Remove enrollment records                     |

***

## Default Role Assignments

These assignments are seeded by the PM-04 database migration (`pf_role_permissions`):

| System Role | Definitions (V/C/E/D) | Schedule (V/C/E/D) | Enrollments (V/C/E/D) |
| ----------- | --------------------- | ------------------ | --------------------- |
| `org_admin` | ✅ ✅ ✅ ✅               | ✅ ✅ ✅ ✅            | ✅ ✅ ✅ ✅               |
| `staff`     | ✅ — — —               | ✅ — — —            | ✅ — — —               |

> **Note:** The `org_admin` role automatically receives all active permissions via the platform trigger. Custom roles can be configured in **Settings > Permissions**.

***

## Managing PM-04 Permissions

1. Navigate to **Settings > Permissions** (requires `org_admin` role).
2. Select the **Practice Management** module from the module list.
3. Locate the Group Definitions, Group Schedule, and Group Enrollments permission groups.
4. Assign or revoke permissions per role using the toggle interface.
5. Changes take effect immediately for newly issued tokens; existing sessions refresh on next page load.

***

## Capacity and Waitlist Configuration

### Capacity Fields

| Field          | Table                  | Description                                    |
| -------------- | ---------------------- | ---------------------------------------------- |
| `max_capacity` | `pm_group_definitions` | Maximum number of enrolled patients. Required. |
| `min_capacity` | `pm_group_definitions` | Minimum patients to hold a session. Optional.  |

### Automatic Capacity Enforcement

When a patient is enrolled via the UI or API:

1. The system counts current enrollments with `status = 'enrolled'` for that group.
2. If the count is **below** `max_capacity`, the patient is enrolled with `status = 'enrolled'`.
3. If the count **equals or exceeds** `max_capacity`, the patient is automatically placed on the waitlist with `status = 'waitlisted'` and assigned the next `waitlist_position`.

### Waitlist Auto-Promotion

When an enrolled patient is **disenrolled** (status changed to `disenrolled`):

1. The system queries the waitlist for that group, ordered by `waitlist_position ASC`.
2. The patient with the **lowest** `waitlist_position` is automatically promoted to `status = 'enrolled'`.
3. Their `waitlist_position` is cleared (`NULL`).
4. A toast notification informs the user of the promotion.

### Manual Override

Administrators can override capacity by directly editing the `max_capacity` field on the group definition. Reducing capacity below current enrollment does **not** automatically disenroll patients — the group will display as over-capacity until resolved manually.

***

## Soft Delete and Data Retention

Group definitions and enrollments use **soft deletion** — the `deleted_at` column is set to the current timestamp, and records are hidden from standard views.

**Soft delete behavior:**

* Records remain in the database for audit and recovery.
* Application queries filter `deleted_at IS NULL`.
* RLS policies enforce this at the database level.
* Schedule occurrences linked to deleted groups are not affected.

**To restore a soft-deleted group definition:**

```sql theme={null}
UPDATE pm_group_definitions
SET deleted_at = NULL, updated_at = NOW()
WHERE id = '<group_id>'
  AND organization_id = '<your_org_id>';
```

**To restore a soft-deleted enrollment:**

```sql theme={null}
UPDATE pm_group_enrollments
SET deleted_at = NULL, updated_at = NOW()
WHERE id = '<enrollment_id>'
  AND organization_id = '<your_org_id>';
```

**Permanent deletion** is not available through the UI and should only be performed by a database administrator in compliance with your organization's data retention policy.

***

## Database Tables

| Table                  | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `pm_group_definitions` | Group metadata: name, type, facilitator, capacity, recurrence |
| `pm_group_schedule`    | Individual session occurrences with date, time, status        |
| `pm_group_enrollments` | Patient enrollment records with status and waitlist position  |

All tables have RLS enabled with `FORCE ROW LEVEL SECURITY`. The `pm_has_org_access` SECURITY DEFINER helper function prevents RLS recursion by checking `organization_id` membership.

### Key Columns

**pm\_group\_definitions:**

* `organization_id` — Tenant isolation (required)
* `group_type` — CHECK constraint: `therapy`, `psychoeducation`, `skills_training`, `support`, `iop`, `php`, `other`
* `facilitator_id`, `co_facilitator_id` — References to staff profiles
* `max_capacity`, `min_capacity` — Enrollment limits
* `deleted_at` — Soft delete timestamp
* `custom_fields` — JSONB for org-specific extensions

**pm\_group\_schedule:**

* `group_definition_id` — FK to `pm_group_definitions`
* `session_date`, `start_time`, `end_time` — Session timing
* `status` — `scheduled`, `completed`, `cancelled`
* `cancellation_reason` — Required when status is `cancelled`

**pm\_group\_enrollments:**

* `group_definition_id` — FK to `pm_group_definitions`
* `patient_id` — FK to `pm_patients`
* `status` — `enrolled`, `waitlisted`, `disenrolled`
* `waitlist_position` — Integer position when waitlisted
* `deleted_at` — Soft delete timestamp

***

## Domain Events

| Event                        | Trigger                      | Payload                                  |
| ---------------------------- | ---------------------------- | ---------------------------------------- |
| `pm_group_session_scheduled` | Session occurrence created   | `{ group_id, session_id, session_date }` |
| `pm_group_session_cancelled` | Session occurrence cancelled | `{ group_id, session_id, reason }`       |

These events are available for downstream consumers (e.g., CL-14 clinical documentation) via the Platform Integration Layer.

***

## Related Resources

* [User Guide](./group-session-scheduling-user-guide.md)
* [PM-04 Specification](../../specs/pm/specs/PM-04-group-session-scheduling.md)
* [Implementation Log](../../specs/pm/IMPLEMENTATION_LOG.md)
* [Patient Registration Admin Guide](./patient-registration-admin-guide.md) (PM-01)
* Platform Permissions: `src/platform/permissions/constants.ts`