> ## 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.

# Clinical Group Sessions

> Manage group therapy sessions and attendance; filter by date range and track status across the organization.

This screen lists group therapy sessions for the current organization and is available at `/cl/group-sessions`.

## Overview

The Group Sessions list page displays sessions stored in `cl_group_sessions`, filtered by a configurable date range (default: last 30 days to today). Summary stat cards show total, completed, and scheduled session counts for the selected window. Each row in the table shows date, topic, group type, time, location, and status. Users with the `cl.group_sessions.create` permission see a **New Session** button that opens the `CreateEditGroupSessionDialog`. Completing a session transitions its status to `completed` and publishes domain events for downstream processing (including billing encounter generation).

## Who it's for

Requires permission: `cl.group_sessions.view`

Creating sessions additionally requires: `cl.group_sessions.create`

## Before you start

You must hold the `cl.group_sessions.view` permission to access this page. Sessions are scoped to your current organization; switching organizations changes the data shown.

## Steps

<Steps>
  <Step title="Open Group Sessions">
    Navigate to `/cl/group-sessions`. The page loads sessions from the past 30 days by default.
  </Step>

  <Step title="Adjust the date range">
    Use the **From** and **To** date inputs to change the window. The list and stat cards update automatically.
  </Step>

  <Step title="Review the sessions table">
    The table shows columns: Date, Topic, Type, Time, Location, Status. Click any row to open the session detail page at `/cl/group-sessions/:sessionId`.
  </Step>

  <Step title="Create a new session (if permitted)">
    Click **New Session** (visible when you have `cl.group_sessions.create`) to open the creation dialog. Fill in the required fields and save.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Session status values">
    The code maps statuses to badge variants: `completed` → default, `in_progress` → secondary, `cancelled` → destructive, all others → outline. The `scheduled` status is tracked in stat card counts.
  </Accordion>

  <Accordion title="Empty and error states">
    When no sessions match the date filter, an empty state with a **Create Session** action (if permitted) is shown. If the data fetch fails, an inline error card with the message "Unable to load group sessions. Please try again." is displayed.
  </Accordion>
</AccordionGroup>

## Detail view

The Group Session detail screen shows session metadata, attendance roster, and per-participant documentation for a single group session at `/cl/group-sessions/:sessionId`.

### Overview

The page loads session metadata from `cl_group_sessions` via `useGroupSessionDetail` and the attendance list via `useGroupAttendanceBySession`. The header shows the session topic, date, and current status badge (`scheduled`, `in_progress`, `completed`, `cancelled`). A Session Details card displays start and end times, location, group type, and attendee count. An Attendance card lists every enrolled participant with their chart ID, attendance status, sign-in/sign-out times, participation level, and a per-row documentation action. Users with `cl.group_sessions.edit` and status not `completed` can edit session metadata via a dialog; users with `cl.group_sessions.edit` and status `in_progress` can mark the session complete, which transitions status to `completed` and publishes a domain event with the present-participant count.

### Who it's for

Requires permission `cl.group_sessions.view`. Additional actions require:

* `cl.group_sessions.edit` — edit session metadata, mark complete
* `cl.group_sessions.delete` — delete session (soft delete)
* `cl.group_attendance.edit` — add attendees
* `cl.group_attendance.document` — write per-participant documentation

### Before you start

* You must have `cl.group_sessions.view`.
* The session must exist and not be soft-deleted.
* To complete a session, it must be in `in_progress` status.

### Steps

<Steps>
  <Step title="Open the session">
    Navigate to `/cl/group-sessions`, then click a session row. The detail page loads session metadata and the attendance roster.
  </Step>

  <Step title="Review session details">
    The Session Details card shows scheduled time window (`actual_start_time`–`actual_end_time`), location, group type, and attendance count relative to `max_capacity` (if set).
  </Step>

  <Step title="Add attendees (optional)">
    If the session is not completed, click **Add Attendee** (requires `cl.group_attendance.edit`) to open the `RecordAttendanceDialog` and enroll a participant.
  </Step>

  <Step title="Document per participant">
    In the Attendance table, click **Document** (or **Edit**) in the Documentation column for a participant row (requires `cl.group_attendance.document`). This opens `IndividualDocumentationDialog` scoped to that attendance record.
  </Step>

  <Step title="Complete the session">
    When the session is `in_progress` and documentation is sufficient, click **Complete Session** (requires `cl.group_sessions.edit`). The mutation counts `present` and `late` attendees and transitions status to `completed`.
  </Step>

  <Step title="Edit session metadata (optional)">
    Click **Edit** (requires `cl.group_sessions.edit`, session not `completed`) to open `CreateEditGroupSessionDialog`.
  </Step>

  <Step title="Delete the session (optional)">
    Click **Delete** (requires `cl.group_sessions.delete`, session not `completed`) and confirm the destructive action. The session is soft-deleted and the user is redirected to `/cl/group-sessions`.
  </Step>
</Steps>

### Key concepts

<AccordionGroup>
  <Accordion title="Session statuses">
    `scheduled` → `in_progress` → `completed`. A session can also be `cancelled`. Only `in_progress` sessions display the **Complete Session** button. Edit and delete are blocked once a session is `completed`.
  </Accordion>

  <Accordion title="Attendance statuses">
    Each row in `cl_group_attendance` carries an `attendance_status` of `present`, `absent`, `excused`, `late`, or `early_departure`. Only `present` and `late` records count toward the participant count passed to `completeSession`.
  </Accordion>

  <Accordion title="Empty and error states">
    * No attendees: "No attendees recorded yet." with an **Add Attendee** button for permitted users.
    * Session not found: "Session not found." with a back link to `/cl/group-sessions`.
    * Loading: skeleton placeholders for both the header and attendance table.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/cl.tsx
  * src/cores/cl/pages/GroupSessionsListPage.tsx
  * src/cores/cl/hooks/useGroupSessions.ts
  * src/cores/cl/pages/GroupSessionDetailPage.tsx
  * src/cores/cl/hooks/useGroupAttendance.ts
  * src/cores/cl/types/group-therapy.ts
</Accordion>