Treatment Plans

Personalized rehabilitation programs — a structured sequence of exercises prescribed to a patient, with tracking, video guidance, and flexible self-service options.

---

What this enables

• Specialists design rehabilitation programs as a sequence of sessions, each containing specific exercises with sets, reps, duration, and rest periods
• Patients follow their program with video guidance directly in the app — no in-person visit required for telerehab
• The platform tracks every session: which exercises were completed, for how long, and at what intensity
• Patients can optionally provide post-session feedback (pain level, difficulty, notes) through a form
• A library of platform-curated and clinic-owned plans is available for self-service — patients with the right subscription can browse and start a plan themselves, no specialist needed
• Specialists clone and customize existing plans — good custom plans can be promoted to the clinic's shared library
• Plans are versioned: changes don't affect patients already enrolled in a previous version

How it works

There are two modes of operation:

Specialist-assigned: A specialist creates or clones a plan, customizes it for a specific patient, and assigns it. The patient receives it in their app and follows the sessions on their own schedule.

Self-service: Patients with a "library access" subscription browse the plan library — filtered by condition, difficulty, body region — and start a plan themselves. No specialist approval needed.

Three scopes

Global plans (platform-curated)
  → "Post-ACL Standard Protocol", "Lower Back Relief 4 Weeks"
  → Visible to all clinics and patients with library access

Org plans (clinic's own reusable library)
  → "Dr. Smith's Shoulder Program"
  → Visible to clinic staff and patients with library access

Custom plans (specialist-created for a specific patient)
  → "Jane Doe – Post-ACL Weeks 1–4" (cloned and customized)
  → Visible to clinic staff and the assigned patient only

Specialists clone a global or org plan and adjust it. If the result works well, an admin can promote it to the clinic's shared library for other specialists to use.

What a session looks like (patient experience)

Patient opens app → sees today's session (one at a time, sequential)
    ↓
Guided flow:
  Video plays → timer/rep counter → rest period → next exercise
  Audio cues signal transitions (exercise start, set end, rest start/end)
    ↓
Optional: camera tracks movement via MediaPipe for form feedback
    ↓
Session complete → post-session questionnaire
    ↓
Progress dashboard: completion rate, pain trends, streak

Flexible scheduling

The plan specifies frequency (e.g., 3× per week). The patient chooses when they do them — no rigid day-level scheduling. If a patient wants to do two sessions in one day, they can; the system counts completions against the weekly target (frequency_per_week), not daily limits. The system tracks completed vs. expected and current streak.

---

Technical Reference

Everything below is intended for developers.

Relationship to other features

Exercise Library  = what exercises exist (content)         → features/exercise-library/
Treatment Plans   = how exercises are prescribed (clinical) ← this feature
Service Plans     = how sessions are billed (commercial)   → features/services/
Telemetry         = how sessions are tracked (analytics)   → features/integrations/telemetry

Key tables

Table	Purpose
treatment_plans	Plan definition — type, frequency, duration, scope, versioning
treatment_plan_versions	JSONB snapshots of plan structure at each publish
treatment_plan_sessions	Template sessions within a plan (ordered blueprints)
treatment_plan_session_exercises	Exercises per session with parameters
patient_treatment_plans	Patient enrollment — assignment, progress, lifecycle
patient_session_completions	Per-session tracking — timing, completion, pain levels
patient_exercise_logs	Per-exercise tracking — prescribed vs actual, video watch %, pose accuracy

Plan types

Type	How it works
telerehab	Patient does exercises at home with video. No specialist appointments.
in_clinic	Specialist schedules in-person sessions via the calendar, linked to appointments.

Exercise parameters per session

Each exercise in a session has a mode that determines which parameters apply:

Rep-based (mode: "reps") — discrete repetitions with an optional per-rep hold:

{
  "mode": "reps",
  "sets": 3,
  "reps": 10,
  "hold_seconds": 5,
  "rest_between_sets_seconds": 30,
  "rest_after_exercise_seconds": 60
}

• reps — number of repetitions per set
• hold_seconds (optional) — how long the patient holds the end position on each rep before releasing (e.g., holding a stretch at peak range for 5 seconds). Controls exercise tempo — a longer hold means a slower, more sustained exercise. Common for stretching and isometric exercises where the therapeutic effect depends on sustained engagement.
• If hold_seconds is NULL, the patient performs reps at their own pace (tapping to count each one).

Duration-based (mode: "duration") — continuous timed exercises without discrete reps:

{
  "mode": "duration",
  "sets": 2,
  "duration_seconds": 60,
  "rest_between_sets_seconds": 45,
  "rest_after_exercise_seconds": 60
}

• duration_seconds — total duration per set in seconds. Used for sustained holds (e.g., prone hang for 60s), continuous activities (e.g., treadmill for 5 minutes), or any exercise where counting reps doesn't apply.

In both modes, the exercise video is a form demonstration — the app timer and rep counter enforce the prescribed pace, not video playback speed.

Versioning

Same pattern as form templates:

1. Plan starts as draft (editable)
2. On publish, current state is snapshotted into treatment_plan_versions as JSONB
3. version counter increments
4. Patient enrollments reference a specific version
5. Editing a published plan creates a new draft; publishing creates a new version
6. Previous versions are immutable (clinical record preservation)

Approval workflow

Configurable per org via treatment_plans.requires_approval:

Without approval:  create → publish → assign → active immediately
With approval:     create → publish → assign (pending_approval) → specialist approves → active

Self-service access check

POST /v1/treatment-plans/{id}/self-assign

1. Patient has active patient_service_plan with library_access = TRUE?
2. Treatment plan has published = TRUE AND visibility = 'library'?
3. Patient has signed the self-service disclaimer form? (reject if missing or unsigned)
4. All pass → create patient_treatment_plan (self_assigned = TRUE, status = active)

The disclaimer is a clinic-configured form (type disclaimer) that the patient must sign before starting any self-service plan. It confirms the patient is choosing the plan without specialist involvement and understands it is not a substitute for professional medical advice. The signed form is linked to the patient_treatment_plan for audit purposes.

Post-session questionnaire

treatment_plans.post_session_form_template_id references a form template. When a session is completed, a form instance is created. Pain/difficulty data is queryable through the existing forms and segments systems.

Service plan integration

Service plan flag	What it unlocks
telerehab_access = TRUE	Specialist can assign telerehab plans to the patient
library_access = TRUE	Patient can browse and self-assign from the plan library

Integration points

• Exercise Library: exercise_id FK — exercise content is always "live" (not snapshotted in plan versions)
• Forms: Post-session questionnaires use the forms system
• Automations: 6 triggers — treatment_plan.created, .assigned, .activated, .session_completed, .completed, .expired
• Appointments (in-clinic): patient_session_completions.appointment_id links in-clinic sessions to appointments
• Telemetry: High-frequency data (pose, video events, bandwidth) forwarded to Telemetry/ClickHouse

Related docs

• API Reference →
• Lifecycle →
• Patient Sessions →
• Tracking →
• Exercise Library →