> ## 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 — User Guide

> Module: PM (Practice Management) | | Version: 1.0

**Module:** PM (Practice Management) | **Spec:** PM-04 | **Version:** 1.0

***

## Overview

Group Session Scheduling lets you define recurring therapy groups, schedule individual sessions, and manage patient enrollment with capacity and waitlist controls. It supports IOP (Intensive Outpatient Program) and PHP (Partial Hospitalization Program) compliance tracking per AHCCCS requirements.

***

## Getting Started

### Navigation

From the sidebar, navigate to **Practice Management → Group Sessions** (or visit `/pm/groups`).

### Required Permissions

| Action                    | Permission Key                                              |
| ------------------------- | ----------------------------------------------------------- |
| View group definitions    | `pm.group_definitions.view`                                 |
| Create/edit groups        | `pm.group_definitions.create` / `pm.group_definitions.edit` |
| Delete groups             | `pm.group_definitions.delete`                               |
| View schedule             | `pm.group_schedule.view`                                    |
| Create/edit occurrences   | `pm.group_schedule.create` / `pm.group_schedule.edit`       |
| Cancel occurrences        | `pm.group_schedule.delete`                                  |
| View enrollments          | `pm.group_enrollments.view`                                 |
| Enroll/disenroll patients | `pm.group_enrollments.create` / `pm.group_enrollments.edit` |
| Remove enrollments        | `pm.group_enrollments.delete`                               |

***

## Creating a Group Definition

1. Click **New Group** on the Group Sessions list page.
2. Fill in the required fields:
   * **Group Name** — Descriptive name (e.g., "Morning CBT Group")
   * **Group Type** — Select from: `therapy`, `psychoeducation`, `skills_training`, `support`, `iop`, `php`, `other`
   * **Facilitator** — Primary clinician running the group
   * **Max Capacity** — Maximum number of enrolled patients
   * **Duration (minutes)** — Standard session length
3. Optional fields:
   * **Co-Facilitator** — Secondary clinician
   * **Location** — Site/room assignment
   * **Min Capacity** — Minimum patients to hold the session
   * **Recurrence Rule** — iCal RRULE for recurring schedule generation
4. Click **Save**.

***

## Managing Schedule Occurrences

### Viewing the Schedule

From a group definition's detail page, select the **Schedule** tab to see all upcoming and past session occurrences.

### Adding an Occurrence

1. Click **Add Session** on the Schedule tab.
2. Set the **Session Date**, **Start Time**, and **End Time**.
3. Confirm or change the **Facilitator** (defaults to the group's primary facilitator).
4. Click **Save**. A `pm_group_session_scheduled` event is published.

### Cancelling a Session

1. Click the session occurrence you want to cancel.
2. Select **Cancel Session**.
3. Provide a **Cancellation Reason**.
4. Confirm. Status changes to `cancelled` and a `pm_group_session_cancelled` event is published.

***

## Managing Enrollments

### Enrolling a Patient

1. From a group definition's detail page, select the **Enrollments** tab.
2. Click **Enroll Patient**.
3. Search and select the patient from the patient registry (PM-01).
4. The system automatically checks `max_capacity` to determine enrollment status:
   * If the group is **below** max capacity, the patient is enrolled with status `enrolled`.
   * If the group is **at capacity**, the patient is automatically placed on the **waitlist** with an assigned position number.
5. A toast notification confirms the enrollment outcome.

### Capacity Indicator

The Enrollments tab displays a capacity bar: **Enrolled / Max Capacity**. When full, the bar changes color to indicate the group is at capacity.

### Waitlist Management

* Waitlisted patients appear in a separate section ordered by `waitlist_position`.
* When an enrolled patient is disenrolled, the system **automatically promotes** the next waitlisted patient (lowest position number) to `enrolled` status.
* A toast notification informs you when an auto-promotion occurs.

### Disenrolling a Patient

1. Click the enrolled patient's row.
2. Select **Disenroll**.
3. Provide a **Reason** (optional).
4. Confirm. The enrollment record is updated (not deleted) for audit trail.

***

## IOP/PHP Compliance

For groups of type `iop` or `php`, the system evaluates AHCCCS compliance requirements:

### IOP Requirements (AHCCCS)

* **9+ hours/week** of structured programming
* **3+ days/week** of sessions
* **3+ hours/day** minimum per session day

### PHP Requirements (AHCCCS)

* **20+ hours/week** of structured programming
* **5 days/week** (daily sessions required)

### Compliance Status

The group detail page displays a compliance badge when the group type is `iop` or `php`:

* **✅ Compliant** — All thresholds met
* **⚠️ Non-Compliant** — Lists specific gaps (e.g., "Need 3 more hours/week")

***

## Soft Delete and Data Retention

* Group definitions and enrollments use **soft delete** (`deleted_at` column).
* Deleted groups are hidden from list views but retained in the database for audit and historical reporting.
* Clinical attendance records (CL-14) linked to schedule occurrences are not affected by group soft-deletion.

***

## Integration with Clinical Documentation (CL-14)

* PM-04 owns the **scheduling** side: group definitions, schedule, enrollments.
* CL-14 (when implemented) owns **clinical documentation**: attendance, progress notes, group therapy notes.
* CL-14 references `pm_group_schedule.id` via the Platform Integration Layer (no direct FK).
* Charge capture (PM-07) is triggered by CL-14's `group_session_documented` event, not by scheduling alone.

***

## Frequently Asked Questions

**Q: Can I edit a group definition after patients are enrolled?**
A: Yes. Changes to group name, facilitator, capacity, etc. take effect immediately. Existing enrollments are not affected.

**Q: What happens when I reduce max\_capacity below current enrollment?**
A: Existing enrollments remain. No patients are automatically disenrolled. The system will show the group as over-capacity until resolved manually.

**Q: Can a patient be enrolled in multiple groups?**
A: Yes. Each enrollment is per-group. A patient can participate in multiple concurrent groups.

**Q: Is facilitator availability checked?**
A: Not in Phase 1. Facilitator availability validation requires PM-05 (Provider Schedule & Availability), which is planned for a future release. Currently, facilitator\_id is a simple reference to the staff profile.

***

## Related Documentation

* [Patient Registration User Guide](./patient-registration-user-guide.md) (PM-01)
* [Insurance & Eligibility User Guide](./insurance-eligibility-user-guide.md) (PM-02)
* [Group Session Scheduling Admin Guide](./group-session-scheduling-admin-guide.md) (PM-04)
* PM-04 Specification: `specs/pm/specs/PM-04-group-session-scheduling.md`