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:
GET /v1/patients/{patientId}/treatment-plans/todayThe 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 3The next session is determined by: (sessions_completed % number_of_session_templates) + 1
Step 2: Pre-Session Pain Check
Before starting, patient reports current pain level using the VAS (Visual Analog Scale):
0 ──────────────────────────── 10
No pain Worst painThis 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_instructionswheretype = '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_instructionswheretype = '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.
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:
- Frontend loads MediaPipe Pose model (runs entirely in browser)
- Camera captures patient's movement in real-time
- Landmark positions compared against expected pose for this exercise
- Accuracy score calculated (0-100)
- Real-time feedback displayed to patient
- 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 commentsThe 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:
- Video caching: Exercise videos can be pre-downloaded for offline playback
- Session data queued: Exercise logs saved locally, synced when online
- Pose tracking works offline: MediaPipe runs entirely in-browser
- 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:
- No video playback — exercises performed under specialist supervision
- Specialist marks completion — specialist or patient marks exercises done via the admin interface
- Linked to appointment —
patient_session_completions.appointment_idreferences the appointment - Post-session questionnaire — still filled by patient (on their device or clinic tablet)
- 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.