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 and finalizes the session as usual.
2. The platform scans every exercise in the workout for any of the following:
   • Patient text comments (any non-empty patientNotes)
   • Recorded pain ≥ 7 / 10
   • Recorded physical exertion ≥ 9 / 10
3. If at least one exercise 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 one or more exercises had pain ≥ 7
   • "[Patient name] left feedback" — otherwise
   • Body: "N exercise(s) flagged in their workout. Tap to view."

The feedback card itself shows:

• A header with the workout date and a contextual headline
• Each flagged exercise as a row with its name
• Pain badge (red ≥ 7, yellow otherwise) and Exertion badge (orange ≥ 9, blue otherwise)
• The patient's free-text note in italics, if present
• A View Full Session button that opens the full session modal (web) or navigates to the workout history (mobile)

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 existing workout details modal pre-loaded with the same session data.
4. The therapist taps an exercise to add or edit a post-exercise note (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.

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 → Workout Details modal (opens from "View Full Session" on a Patient Feedback Summary card)
Therapist mobile	Messages tab → conversation thread → Session Viewer screen, OR navigate directly via push notification tap

The Session Viewer screen is also where therapists actually edit notes — note editing is currently mobile-only.

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 existing workout details modal from a feedback card on the therapist side
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.