Patient–Therapist Feedback

Overview

The patient–therapist feedback feature creates a structured, two-way feedback loop that surfaces inside the existing messaging conversation between a patient and their connected therapist(s). When a patient finishes a workout with high pain, high exertion, or written comments, the system automatically posts a Patient Feedback Summary card to the conversation and pushes a notification to every connected therapist. When a therapist reviews that session and adds post-exercise notes, the platform bundles those notes into a single Doctor Feedback Note card and pushes it back to the patient.

The feature is gated by the feedbackNotifications per-tenant feature flag (toggled from /admin/feature-flags). See Feature Flags for how flags work.

Why it exists

Before this feature, patient pain and exertion scores lived only in the workout history table — therapists had to actively go look for them. Conversely, the only way for a therapist to react to a hard session was to type a free-form chat message. This feature closes both gaps so important feedback never gets lost in a list, and so therapists can leave structured per-exercise notes that the patient is guaranteed to see.

Patient → Therapist Flow

1. The patient completes a workout — through the guided flow or the dashboard's Mark as finished quick-finish (see Patient Workout Completion).
2. The platform scans every exercise in the workout — and, since August 2026, the session-level feedback the patient can leave for the whole workout — for any of the following:
   • Patient text comments (any non-empty note, per exercise or session-wide)
   • Recorded pain ≥ 7 / 10
   • Recorded physical exertion ≥ 9 / 10
3. If at least one exercise or the session-level feedback matches, the system posts a PATIENT_FEEDBACK_SUMMARY card to the existing conversation between the patient and their connected therapist(s). For a patient with one therapist, the message goes into the one-on-one conversation; for a patient with multiple therapists, it goes into the group conversation that contains everyone.

4. Each connected therapist receives a push notification:

   • "[Patient name] reported high pain" — when any exercise or the session-level rating had pain ≥ 7
   • "[Patient name] left feedback" — otherwise
   • Body: "N exercise(s) flagged in their workout. Tap to view." — or "They left feedback on their session." when only session-level feedback was flagged

   The exercise-scoped headline ("reported high pain on: …") only claims high pain when an exercise itself reported it — session-level pain is never attributed to exercises that were flagged for notes alone.

The feedback card itself shows everything the patient typed, so the therapist reads it in the thread without opening the session:

• A header with the workout date and a headline written on the reader's side in their language ("Maria reported high pain on: Step-ups", "Maria left feedback on their session"); high pain is only claimed for the exercises that reported it
• How it went: the session's pain and effort as chips and the patient's note for the whole session, in full (since 2026-10-21 on the web and in the app; before, the card only listed exercises and a session-only note was invisible until the session was opened)
• Each flagged exercise as a row with its name, its pain and effort as chips (pain in its own colour: calm up to 3, amber 4–6, red from 7; a very hard effort of 9 or more in amber) and the patient's note in full
• An Open session button that opens the session sheet (web) or the Session Viewer (app)

In the conversation list (web and app), a feedback card previews the patient's own words (the session note first, otherwise the first exercise note, in quotes) instead of the headline.

Only one summary card is ever posted per workout — re-finalizing or recomputing the same workout will not create duplicates.

Therapist → Patient Flow

1. The therapist taps the push notification (or opens the messages tab and taps View Full Session on the patient feedback card).
2. On mobile, the therapist lands on the new Session Viewer screen — a per-exercise list showing the patient's actual sets/reps/duration, prescribed pain and exertion targets vs. recorded values, and any patient notes. Each exercise has an Add note button (or, if a note already exists, a tappable existing note).
3. On web, the therapist's messages page opens the session sheet (the same one the patient popup and the dashboard's Sessions tab open) pre-loaded with the same session data.
4. The therapist adds or edits the feedback on an exercise (Add feedback under the exercise, max 1000 characters) and saves.
5. Saving the first note for that session schedules a 5-minute coalescing window. Any additional notes the therapist saves within that window reset the timer — the patient is not notified yet.
6. When the timer expires, the platform bundles every post-exercise note the therapist has saved on that workout into a single DOCTOR_FEEDBACK_NOTE card and posts it to the conversation.
7. The patient receives one push notification: "Your therapist reviewed your session" / "[Doctor name] left notes on N exercise(s). Tap to view."
8. If the therapist later edits any of those notes, the previous card is replaced with an updated one (the patient sees the latest content, never an inconsistent half-version).

The feedback card on the patient side shows the doctor's name, the workout date, and each annotated exercise with its name and the therapist's note.

Sample patients

A therapist's sample patient (internal/sample-patient.md) arrives with one therapist-notes card and one patient-feedback card already in its conversation. Notes the owner leaves on a sample session post a new therapist-notes card to that thread (the owner is the sample's only therapist), and nothing is pushed to the sample.

Where it lives

Surface	Where to look
Patient web	Messages tab → conversation thread → Patient Session Detail modal (opens from "View Full Session" on a Doctor Feedback Note card)
Patient mobile	Messages tab → conversation thread → tapping "View Full Session" routes to the workout history tab
Therapist web	Messages tab → conversation thread → session sheet (opens from "View Full Session" on a Patient Feedback Summary card); also from the patient popup's Workouts tab and the dashboard's Sessions tab
Therapist mobile	Messages tab → conversation thread → Session Viewer screen, OR navigate directly via push notification tap

Therapists edit per-exercise feedback on either surface: the Session Viewer screen in the app, or the session sheet on the web.

Feature flag

The feedbackNotifications flag is per-tenant and disabled by default. Both feedback flows check the flag at the service layer, so disabling it stops new feedback messages from being created and stops new push notifications from being sent. Existing feedback cards already in conversations remain visible.

Toggle from the admin panel: /admin/feature-flags.

Key Files

File	Role
OktaPT-FE/components/messaging/FeedbackMessageBubble.tsx	Web feedback card renderer (delegates from MessageBubble.tsx based on message.type)
OktaPT-FE/components/patient/PatientSessionDetailModal.tsx	Patient-side "View Full Session" modal
OktaPT-FE/pages/patient/messages.tsx	Wires the patient session modal into the messages page
OktaPT-FE/pages/doctor/messages.tsx	Opens the session sheet from a feedback card on the therapist side
OktaPT-FE/components/doctor/sessions/SessionSheet.tsx	Therapist-side session sheet: the session's summary, exercises, per-exercise feedback and the note to the patient; lib/utils/sessionViews.ts derives what the lists and the sheet show
Okta-Mobile/components/messaging/FeedbackMessageBubble.tsx	Mobile feedback card renderer
Okta-Mobile/app/(doctor)/(session-viewer)/view.tsx	Therapist Session Viewer screen — review session and edit per-exercise notes
Okta-Mobile/app/conversation/[id].tsx	Routes "View Full Session" taps to the Session Viewer (doctor) or workout history (patient)
OktaPT-FE/pages/admin/feature-flags.tsx	feedbackNotifications toggle in the admin feature-flags table

For engineers, the data model, queue, and worker internals are documented in internal/feedback-messages.md.