Patient Session Execution

Overview

This document describes the patient-side experience of executing a telerehab session — from opening the app to completing the post-session questionnaire.

Session Flow

┌─────────────────────────────────────────────────────┐
│  1. TODAY'S SESSION                                 │
│  Patient opens app → sees today's plan              │
│  GET /v1/patients/{id}/treatment-plans/today        │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  2. PRE-SESSION                                     │
│  Pain level check (VAS 0-10)                        │
│  "How is your pain right now?"                      │
│  POST .../sessions/{num}/start                      │
│  { "pain_level_before": 6 }                         │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  3. EXERCISE LOOP (for each exercise)               │
│  ┌───────────────────────────────────────────┐      │
│  │  a. INSTRUCTIONS                          │      │
│  │  Show exercise name, preparation steps    │      │
│  │  Optional: display contraindications      │      │
│  └─────────────────────┬─────────────────────┘      │
│                        │                             │
│  ┌─────────────────────▼─────────────────────┐      │
│  │  b. VIDEO PLAYBACK                        │      │
│  │  Exercise video plays (HLS adaptive)      │      │
│  │  Patient watches demonstration            │      │
│  │  Track: video_watch_seconds, percentage   │      │
│  └─────────────────────┬─────────────────────┘      │
│                        │                             │
│  ┌─────────────────────▼─────────────────────┐      │
│  │  c. EXERCISE EXECUTION                    │      │
│  │  Rep counter OR hold timer                │      │
│  │  Set tracking (Set 1/3, Set 2/3, ...)    │      │
│  │  Rest timer between sets                  │      │
│  │  Optional: pose tracking via camera       │      │
│  └─────────────────────┬─────────────────────┘      │
│                        │                             │
│  ┌─────────────────────▼─────────────────────┐      │
│  │  d. LOG & ADVANCE                         │      │
│  │  PUT /v1/patient-exercise-logs/{id}       │      │
│  │  Rest timer before next exercise          │      │
│  │  OR skip exercise (with reason)           │      │
│  └─────────────────────┬─────────────────────┘      │
│                        │                             │
│              ◄─── Next exercise ───┘                 │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  4. POST-SESSION                                    │
│  Pain level check (VAS 0-10)                        │
│  Perceived difficulty (1-5)                         │
│  Optional notes                                     │
│  POST .../complete                                  │
│  { "pain_level_after": 4, "difficulty": 3 }        │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  5. QUESTIONNAIRE (if configured)                   │
│  Post-session form from form template               │
│  Pain evolution, mobility assessment, etc.          │
│  Uses existing forms system                         │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  6. SUMMARY                                         │
│  Session summary: exercises done, time, pain trend  │
│  Progress update: "6 of 12 sessions complete!"     │
│  Streak counter, motivational feedback              │
└─────────────────────────────────────────────────────┘

Detailed Step Breakdown

Step 1: Today's Session

The patient's home screen shows their active treatment plan and today's session — one session at a time, not the full plan. The patient must complete the current session before the next one becomes available. This enforces sequential progression, which is important for rehabilitation programs where exercises build on each other.

GET /v1/patients/{patientId}/treatment-plans/today

The response includes:

• Which session template to perform next (sessions cycle through the plan's templates)
• Full exercise list with video URLs, instructions, and parameters
• Current progress (sessions done, completion %)

Session rotation logic: If a plan has 3 session templates and runs for 4 weeks (12 total sessions):

Week 1: Session 1, Session 2, Session 3
Week 2: Session 1, Session 2, Session 3
Week 3: Session 1, Session 2, Session 3
Week 4: Session 1, Session 2, Session 3

The next session is determined by: (sessions_completed % number_of_session_templates) + 1

Why sequential, not open access: Patients see only the next session, not the entire plan. This prevents skipping ahead or cherry-picking easier exercises. In progressive rehabilitation, earlier sessions prepare the body for later ones — doing them out of order can reduce effectiveness or increase injury risk. The specialist designs the session order intentionally, and the platform enforces it.

Step 2: Pre-Session Pain Check

Before starting, patient reports current pain level using the VAS (Visual Analog Scale):

0 ──────────────────────────── 10
No pain                    Worst pain

This is stored as patient_session_completions.pain_level_before and compared with pain_level_after for trend tracking.

Step 3: Exercise Execution

a. Instructions Screen

For each exercise, the patient first sees:

• Exercise name and description
• Preparation instructions (from exercise_instructions where type = 'preparation')
• Safety warnings (from exercise_contraindications)
• Equipment needed (from exercise tags)
• What to expect: "3 sets of 10 reps, 30s rest between sets"

b. Video Playback

The exercise demonstration video plays:

• HLS adaptive streaming (auto-adjusts quality to network)
• Patient can replay, pause, skip video
• Video watch time tracked: video_watch_seconds, video_watch_percentage
• Form cues displayed as overlays or captions (from exercise_instructions where type = 'form_cue')

Frontend sends video events to Telemetry:

POST /v1/media/events (Telemetry)
{
  "event_type": "exercise_video.watch",
  "organization_id": 1,
  "patient_id": 123,
  "exercise_id": "660e8400-...",
  "session_completion_id": 789,
  "watch_seconds": 38,
  "total_seconds": 42,
  "percentage": 90.48
}

c. Exercise Execution with Timer

For rep-based exercises:

┌──────────────────────────────┐
│  Straight Leg Raise          │
│                              │
│  Set 2 of 3                  │
│  Rep: 7 / 10                 │
│                              │
│  [  TAP TO COUNT REP  ]     │
│                              │
│  Next: 30s rest              │
└──────────────────────────────┘

Patient taps a button for each rep. After completing the prescribed reps, the rest timer starts automatically.

For duration-based exercises:

┌──────────────────────────────┐
│  Prone Hang                  │
│                              │
│  Set 1 of 2                  │
│  Hold: 0:42 / 1:00           │
│                              │
│  ████████████████░░░░        │
│                              │
│  Next: 45s rest              │
└──────────────────────────────┘

A countdown timer tracks the hold duration. Auto-advances to rest period when timer completes.

Audio cues:

The app plays audio signals at key transition points so patients can follow along without watching the screen (important for floor exercises, prone positions, etc.):

Event	Sound
Exercise starts	Distinct start tone
Set complete	Short completion chime
Rest period starts	Rest tone
Rest period ends (next set)	Start tone
Exercise complete	Completion chime
Session complete	Final completion sound

Audio cues are played by the frontend and can be muted by the patient via a session-level toggle. Mute preference is stored locally (not synced to server).

Rest periods:

┌──────────────────────────────┐
│  Rest                        │
│                              │
│  0:18 / 0:30                 │
│                              │
│  Next: Set 3 of 3            │
│                              │
│  [ SKIP REST ]               │
└──────────────────────────────┘

Between-set rest uses rest_between_sets_seconds. Between-exercise rest uses rest_after_exercise_seconds.

d. Pose Tracking (Optional)

If the patient's device has a camera and they opt in, MediaPipe pose detection provides real-time feedback:

┌──────────────────────────────┐
│  🎥 Camera Active            │
│                              │
│  ┌────────────────────────┐  │
│  │                        │  │
│  │   [Patient skeleton    │  │
│  │    overlay with        │  │
│  │    landmark points]    │  │
│  │                        │  │
│  └────────────────────────┘  │
│                              │
│  Form Score: 85/100          │
│  ✓ Knee extension good       │
│  ⚠ Keep shoulders level      │
└──────────────────────────────┘

How it works:

1. Frontend loads MediaPipe Pose model (runs entirely in browser)
2. Camera captures patient's movement in real-time
3. Landmark positions compared against expected pose for this exercise
4. Accuracy score calculated (0-100)
5. Real-time feedback displayed to patient
6. Aggregated pose data sent to Telemetry:

POST /v1/media/events (Telemetry)
{
  "event_type": "exercise_pose.track",
  "organization_id": 1,
  "patient_id": 123,
  "exercise_id": "660e8400-...",
  "session_completion_id": 789,
  "pose_accuracy_score": 85.5,
  "feedback": ["knee_extension_good", "shoulders_uneven"],
  "timestamp": "2026-02-16T09:05:00Z"
}

Privacy:

• All pose processing happens on-device (no video sent to server)
• Only aggregated scores and landmark data sent to Telemetry
• Patient must opt in to camera tracking
• Biometric consent required (can be triggered via automation)

Step 4: Post-Session

After all exercises are done (or skipped), the patient completes the session:

POST /v1/patient-session-completions/{id}/complete
{
  "pain_level_after": 4,
  "perceived_difficulty": 3,
  "notes": "Felt good overall"
}

Step 5: Post-Session Questionnaire

If the treatment plan has a post_session_form_template_id, a form instance is automatically created:

The form might include:
- Pain location (body map selector)
- Pain quality (sharp, dull, burning, aching)
- Range of motion self-assessment
- Swelling observation
- Medication taken today?
- Sleep quality last night
- Additional comments

The form uses the existing forms system — organizations customize the questionnaire through the form template designer.

Step 6: Session Summary

After completion, the patient sees a summary screen:

┌──────────────────────────────────────┐
│  Session Complete! 🎉               │
│                                      │
│  Duration: 28 minutes                │
│  Exercises: 3/3 completed            │
│  Pain: 6 → 4 (improved!)           │
│                                      │
│  ────────────────────────            │
│                                      │
│  Progress: 6 of 12 sessions         │
│  ████████████░░░░░░░░░░░ 50%        │
│                                      │
│  Streak: 3 days in a row 🔥         │
│                                      │
│  Next session: Tomorrow              │
│                                      │
│  [ VIEW PROGRESS ]  [ DONE ]        │
└──────────────────────────────────────┘

Offline Considerations

For patients with unreliable internet:

1. Video caching: Exercise videos can be pre-downloaded for offline playback
2. Session data queued: Exercise logs saved locally, synced when online
3. Pose tracking works offline: MediaPipe runs entirely in-browser
4. Sync on reconnect: All pending exercise logs and session completions sync automatically

The frontend should implement a service worker for offline video caching and a local queue for API calls.

In-Clinic Session Differences

For in_clinic plans, the session execution differs:

1. No video playback — exercises performed under specialist supervision
2. Specialist marks completion — specialist or patient marks exercises done via the admin interface
3. Linked to appointment — patient_session_completions.appointment_id references the appointment
4. Post-session questionnaire — still filled by patient (on their device or clinic tablet)
5. No pose tracking — specialist provides form feedback directly

The API calls are the same, but the frontend presents a simplified interface for in-clinic use.