Otera Health Documentation

This directory contains documentation for the Otera Health products (web and mobile).

Contents

File	Description
CHANGELOG.md	Changelog for the Otera Health project.
detailed-changes	Directory containing detailed changes for the Otera Health project.
web-translations.md	How to add/maintain translations in the OktaPT-FE web app. Covers i18n file structure, variable interpolation ({{name}}), validation script, and best practices.
mobile-translations.md	How to add/maintain translations in the Okta-Mobile React Native app. Covers the custom I18nManager, variable syntax, language detection, and differences from web.
patient-onboarding.md	Patient invitation and onboarding flows from the therapist's perspective. Covers magic link (remote) and QR code (in-clinic) onboarding methods, and the sign-in link for a patient who already set up their account.
patient-workout-completion.md	How patients finish workouts (August 2026 redesign). Covers the 2-tap exercise loop, dashboard quick-finish ("Mark as finished"), server-backed resume with the progress envelope, automatic completion, session-level feedback, and the shared completion side-effect service.
workout-logbook.md	The workout logbook (per-clinic flag): the whole session on one screen logged set by set, with the video on tap and pain/effort asked once; Vary by set (12 / 10 / 8, a range, max) and a note per block for therapists; what the patient logged in the session details; last time's result under each exercise for the patient and the therapist.
internal/workout-logbook.md	Workout logbook internals: the setPlan and blockNotes JSON columns, the CompletedExerciseSet rows, the shared setPlan module in all three repos, every write path and the old-client rules, the LIST envelope, loggedSets and sessionFeedback on the progress endpoint, the web and mobile files, tests and open items.
internal/assistant-prototype.md	Assistant prototype (2026-10-26): one box to ask about patients, plans and progress or to say what to note or send. The product position (a layer over the screens, the model routes and never writes the facts, writes are confirmed proposals, the price is shown), the tool catalog per role and its authorization, the two endpoints and card shapes, the web and app parts, what was verified and what is open. Behind the assistant (therapists) and patientAssistant (patients) flags.
patient-workout-management.md	How therapists create, edit, and manage patient workout plans. Covers initial plan creation, AI plan generation and editing, exercise blocks, and the edit plan modal.
therapist-ai-plan-generation.md	Technical deep-dive into AI-powered initial plan generation. Covers the complete flow from doctor notes input through SSE streaming to database storage, including OpenAI integration details.
self-serve-plans.md	The app's self-serve plan builder ("I'm New Here") and plan updater ("Adjust your plan", "Manage your plan" on the web): what the person sees, warning signs, languages, and the selfServePlanUpdates flag (on for the main site, off for clinics).
exercise-media-rendering.md	How exercise thumbnails and videos are rendered from different video sources (Kinescope, Cloudflare Stream, YouTube). Covers the priority-based fallback system, utility functions, player components, and PDF export handling.
exercise-scope-service.md	How to use the exercise scope helper for consistent exercise visibility filtering. Covers visibility modes, tenant middleware interaction (platform-wide exercises have no tenant and are read everywhere), usage examples, explicitTenantId, and the tag-visibility and platform helpers.
feedback-board.md	Public product feedback forum at /feedback. Covers browsing and sorting, posting with attachments, up/down voting, comments, statuses and official responses, and where the entry points live. Cross-tenant and unauthenticated by design.
internal/feedback-board.md	Feedback board internals. Covers the four Prisma models, the public and admin endpoint set, HN-style trending ranking, row-locked vote transactions, the presigned-upload + HeadObject verification pipeline, honeypot and anonymous-only rate limits, and the Telegram/SendGrid notification paths.
plan-assistant.md	The plan assistant of the HEP builder (flag planAssistant): the therapist says what should change in words and it happens on the week in front of them, step by step, with Undo; adds, dose changes on some days only, moves, swaps, a day's sessions swapped or put in order, copying a day, repeating a past session ("the same as last Tuesday"), templates, and a first week from the notes. What it sees, what it asks, what it never touches.
hep-builder.md	The beta HEP builder — a full-screen plan builder with list/week/split views, prescription rows with cadence presets, a persistent drag-from exercise palette, copy-a-day, and a docked AI assistant. Opt-in per browser; the classic modals remain the default.
feature-flags.md	How per-tenant feature flags work. Covers the database schema, backend guard pattern, frontend Zustand store, and step-by-step guide for adding new flags.
homepage-brand-routing.md	How / resolves to three different homepages (Otera, OKTA, custom tenant) via NEXT_PUBLIC_BRAND_NAME. Covers build-time brand switch, runtime hostname-based parent-brand detection, the section components, the marketing navigation, the /team and /careers pages and their content files, the /patients route, and shared marketing components.
infrastructure-diagram.md	Infrastructure and deployment diagram.
mobile-keyboard-handling.md	Keyboard handling patterns in the mobile app.
mobile-navigation-design.md	Mobile navigation design system. Covers the Duolingo-inspired floating tab bar, per-tab accent colors, animated indicators, streak header widget, and screen header styling.
ai-integration-guide.md	How the Okta-Health project integrates with the OpenAI API. Covers the API key management, model selection, and response formatting.
api-architecture-and-testing.md	API modular architecture and testing strategy. Covers the createApp() factory, multi-client Prisma strategy, service singletons, and how to write tests.
rtm-billing.md	High-level overview of the full RTM billing system. Quick reference for all 6 CPT codes, dashboard structure, API endpoint index, and links to detailed docs.
internal/rtm-clinician-time-audit.md	October 2026 clinician time audit: web/API corrections, mobile integration, validation evidence and release checks.
clinic-administrators.md	Clinic administrators. Who they are (an administrator account or a therapist with rights), how the platform admin creates the first one, and the clinic area: overview, therapists (invite, approve, deactivate, move their patients), patients (care team changes), administrators.
claims-portal.md	Insurance claims through the Stedi clearinghouse: the clinic's billing setup and fee schedule, patients' insurance and real-time coverage checks, the RTM periods ready to bill, the checks that stop a bad claim, sending, payer responses with rejection and denial reasons explained, corrections and voids. Clinic area tab and admin tool.
internal/clinic-administrators.md	Clinic administrator internals. CLINIC_ADMIN account type and where its session may go, the tenant-scoped ClinicAdministrator row, the requireClinicAdministrator guard, the /v2/clinic-admin and /v2/admin/clinic-administrators endpoints, web routing and gate, mobile refusal, tests.
internal/plan-assistant.md	Plan assistant internals: the operations contract (POST /v2/ai/plan-assistant, strict schema, resolution of ids, names, past sessions and templates, locked days), the stream, the prompt and its cacheable prefix, the models and measured timings, the client reducer and hook, and what is not covered yet.
internal/self-serve-plans.md	Self-serve plan internals. Covers the six /v2/ai endpoints and their gates (the flag, the adoption check, the web's older routes), the stream events, OpenAI Decisions triage and the 25-exercise shortlist with their own breakers, the writer models and limits, warning-sign handling, the plan check, persistence under the plan lock with the schedule recorded, old-client shapes, and the mobile and web files.
internal/claims-portal.md	Insurance claims internals. Stedi configuration (STEDI_API_KEY, STEDI_API_MODE, STEDI_API_URL), the claims models, services and endpoints, every pre-submission check by code, the CMS-1500 payload mapping, the 277CA / 835 polling and matching, tests, and what is out of scope.
scheduling.md	Scheduling (tenant flag scheduling). The clinic's calendar per therapist, appointment types and locations, working hours and time off, booking (single or a weekly run), moving, cancelling, the steps of the day, reminders that ask for a confirmation, the waitlist that fills cancellations, the patient's own booking on web and app, the intake before a first visit that AI reads for the therapist, and the AI pre-visit brief.
internal/scheduling.md	Scheduling internals. The data model, the availability engine (windows, buffers, classes, lead time), the booking lock, reminders as delayed jobs, the waitlist offers and sweep, the intake and brief AI steps, the link tokens, every endpoint, the web and mobile files, tests.
clinical-documentation.md	Clinical documentation (tenant flag clinicalDocumentation). Visit notes of six types started from an appointment, a video visit or the chart, the plan of care with its certification and the case it treats, SMART goals, outcome measures with their meaningful change and questionnaires sent to the patient, measurements imported from the clinic's own tests, special tests and strength, templates, the referral read by AI and the documents on the record, the home program built from the evaluation, the AI first draft labelled in words, coding with the 8-minute rule, sign-and-lock with amendments, the after-visit summary to the patient, the therapist's Notes worklist, the clinic's Documentation tab and settings, the visit fee schedule, signed notes in To bill, and the Medicare rules in plain words.
internal/clinical-documentation.md	Clinical documentation internals. The data model and migrations, the services, the note content document and the sign checks, the units rule, the compliance engine and its flags, the draft's context and prompt rules, templates, questionnaires and their sweep, documents and the referral reading, signing, amendments and voiding, the claims bridge and the new scrub codes, the hourly sweep, the notifications, every endpoint, the access rules, the web and mobile files, tests and environment.
therapist-patient-assignment.md	How multi-therapist assignment works. Covers assigning therapists at invite time and from the dashboard, API endpoints, frontend components, and the therapistPatientAssignment feature flag.
rtm-cpt-billing-dashboard.md	Workout-based RTM billing (98975, 98985, 98977). Covers billing records, kanban board, insights, nudge emails, projected codes calculator, and the In Progress sub-tabs.
rtm-time-based-billing.md	Time-based RTM billing (98979, 98980, 98981). Covers the time tracking hook, heartbeat model, multi-tab coordination, beacon delivery, time progress table, and attestation flow.
design-system.md	The design system for every surface (decided 2026-10-12): the three priorities, color, type, spacing, shape and motion tokens with their web classes and app keys, the sixteen components, patterns per surface, voice rules and the rollout order.
dob-input-component.md	Technical documentation for the DOBFieldInput component. Covers the three-field date input design, locale-aware field ordering, validation rules, and usage examples.
exercise-canonicalization.md	Automatic AI-powered duplicate exercise detection and merging. Covers the 2-stage pipeline (exact match + AI fuzzy match), merge transaction logic, audit trail, and the exerciseAutoCanonicalization feature flag.
clinical-assessment.md	Clinical assessment for therapists (mobile 2.2.0). Covers structured camera tests for the shoulder, knee, elbow, hip, ankle, neck and trunk, the ten-step shoulder protocol, the recording setup screen, live skeleton/goniometer tracking with framing hints, the hold-still countdown, review and retake, quality retakes, passive tests with the phone laid on the body (inclinometer), the measured range-of-motion results card with in-app playback, and motion-tracking settings.
measure-app.md	Otera Measure, the screening tools as an app of their own for clinicians. Covers the welcome, measuring without an account and saving to one, sign-up and sign-in with Google, Apple or a password, the home of the measuring tools, the 14-day trial and the store subscription (RevenueCat), settings and account deletion, the build variant and what to configure for a release.
social-sign-in.md	Sign in with Google and Apple on the web and in the Otera and OKTA apps (flag socialSignIn): an account a therapist created signs straight in with the matching email, the app finds the clinic or asks which, the main sites' sign-up with a provider, and why clinic sites have no sign-up form. Set-up: web clients, Google and Apple registration, the app's 2.3.0 build.
internal/clinical-video-assessment.md	Clinical video assessment internals. Covers the 7-screen mobile flow, structured test fields and protocol runs, the on-device pose engines (Nitro module) and countdown, the API routes incl. quality rejection and playback, the data model and state machine, the resumable BUSY-aware pipeline, prompt v2, the video-analysis-service contract, S3 layout and environment variables.
leaderboards.md	Leaderboards for patients (weekly, under nicknames) and therapists (monthly): points for the share of planned sessions done, the podium of three, the three ahead and the viewer, tiers, benchmarks against history, the recap, the worklist, the three flags, and the internals (models, jobs, endpoints, exclusions).
streaks.md	How the streak system tracks patient workout consistency. Covers daily/weekly streak logic, timezone-aware calculations, the data model, API endpoints, and frontend rendering across web and mobile.
sms-consent.md	Public SMS text-messaging consent / opt-in page (/sms-consent). Covers message types, consent terms, message frequency and rates, and STOP/HELP opt-out instructions.
mobile-ui-ux-design.md	Mobile UI/UX design system and patterns.
mobile-role-separation.md	Patient/Doctor role separation in the mobile app. Covers RoleGuard, route groups, httpClient singleton, dashboard split, ESLint import boundaries, and typed route pitfalls.
personalized-exercise-videos.md	Personalized exercise videos end-to-end. Covers the doctor recording flow, S3-to-Cloudflare processing pipeline, patient video library and exercise history browsing, API endpoints, and the therapistPersonalizedExerciseVideo flag.
smart-notifications.md	Smart notifications system (internal). Covers the AI-powered notification engine: engagement segments, smart timing, anti-annoyance filter, content generation, celebrations, channel selection, admin controls, mobile integration, and data model.
mobile-workout-flow.md	Mobile workout flow and design. Covers the full workout state machine, screen-by-screen UI design (setup, execution, recording, completion), progress indicators, feedback modal, exercise info sheet, and Android safe area handling.
exercise-library.md	The exercise library end-to-end. Covers therapist and patient experience, data model, tag system, create/edit form, API endpoints, security (auth, ownership, tenant isolation, media), filtering, exercise blocks/types, and the exercise-to-workout pipeline.
exercise-ai-search.md	Semantic "Search with AI" for therapists across the exercise library and the plan/HEP exercise picker. Covers the shared hook and closest-matches endpoint, candidate scoping (video/photo-backed, visible exercises), pinned AI results with badges, and rate/timeout limits.
mobile-doctor-dashboard.md	Mobile doctor dashboard redesign (May 2026). Covers the patient list with compliance grades and flag chips, My/All patients toggle, "Seeing today" workflow, patient detail screen with action grid, Quick Analysis (flags, suggested notes, next-up, last-completed), All Sessions, and the Re-onboard Patient modal.
mobile-doctor-hep-management.md	Mobile HEP management for doctors. Covers session-based plan viewing, inline dosage editing, AI-powered plan modifications, exercise picker, and the therapistMobileHepManagement feature flag.
mobile-exercise-management.md	Mobile exercise management tab for doctors. Covers the full Exercises tab implementation: tab registration (cyan, feature-flagged), exercise list with search/filter/segments, tag filter bottom sheet, exercise detail/create/edit screens, media capture via expo-image-picker, types/service/hooks, Hermes engine compatibility notes, and differences from the web exercise library.
admin-panel.md	Admin panel documentation. Covers dual-layer auth (backend middleware + frontend route guard), the 18-page admin area (notifications, feature flags, user management, admin creation, patient-therapist assignments, feature announcements, therapist onboarding, the sample patient page, notification observatory, admin scripts), and 7 analytics dashboards (retention, conversion, LTV, growth, therapist effectiveness, notification impact, workout stats).
internal/app-entrance-tracking.md	App entrance tracking system. Covers the inferred workout pipeline: AppEntrance data model, status lifecycle, BullMQ finalization queue, mirror workout creation, streak rebuild, RTM billing recalc, and frontend badges.
internal/auth-session-management.md	Auth overhaul (Aug 2026). Covers the sliding 365-day device sessions, 15-minute access tokens with refresh rotation and replay revocation, silent legacy-token upgrade, tri-state web auth store, CSRF/rate-limit middleware, and the RU direct-path cookie nuance.
internal/same-origin-api-proxy.md	The web app's /api/backend proxy: how a call travels, the shared secret that gives the API the visitor's address, X-Long-Running for slow answers, the settings on each side, and self-hosting behind nginx.
internal/tenant-branding.md	A tenant's branding on its row: logo, colour, parent brand, language; the public /v2/branding routes by host, the admin endpoints, the app's clinic list, and the backfill of existing clinics.
internal/mobile-store-release.md	How Okta-Mobile builds reach the App Store and Google Play: the apps and their ids (Okta Health's Play package differs from its bundle id), store build versus EAS update, the iOS and Android eas build --auto-submit recipes, the Play helper for tracks, promotion and listings, country split, push (FCM) files and keys, what stays manual in each console.
internal/kinescope-video-copies.md	Our copies of the Kinescope library's videos. Covers the global KinescopeExercise table (one row per Kinescope video), the npm run kinescope-videos script that downloads each video with kinescope-dl, checks it for gaps and cuts and uploads it to the Spaces bucket all environments share, and how to run it per database.
internal/kinescope-video-generation.md	Kinescope studio → AI demo videos and description checks. Covers the admin page for the Kinescope library's videos (sorted by name or by usage in plans), Kinescope's posters as @image2 (copied into Spaces on first use, npm run kinescope-thumbnails for all of them), what differs from the MedBridge pipeline it shares, using a finished video in the exercise library in place of the Kinescope one as a worker job and switching back, the AI check of each exercise's patient instructions against its video with the new instructions it proposes, the overlap with the MedBridge import found by name with an admin's confirmations, the AI videos shared between exercises marked the same, endpoints and the data model.
internal/medbridge-exercise-import.md	MedBridge exercise staging layer. Covers the two global (non-tenant) Prisma models keyed by MedBridge IDs, the idempotent CLI importer with category taxonomy, and the admin browse/search endpoints feeding AI demo generation.
internal/medbridge-video-generation.md	MedBridge → AI demo videos (Seedance 2.5 on Higgsfield). Covers the admin panel, the AI prompt writer (the team's instructions, sampled video frames, @image2), the reference-to-video request, the attempt state machine with token-owned BullMQ steps, retries, idempotent submits and recovery, the exercise library button (one platform-wide exercise with a Cloudflare video, AI-written instructions and tags, switching the video, removing it), configuration, endpoints and the data model.
internal/platform-exercise-library.md	Platform-wide exercises (the Kinescope library, MedBridge AI videos): one row with no tenant that every tenant reads. Covers the tenant-middleware read scope, the helpers for code, the admin panel page and endpoints, the consolidation script that folds per-tenant copies, the migration and rollback.
internal/system-templates.md	System workout templates: the ready-made sessions every clinic's therapists see and copy. Covers the tenant-less WorkoutTemplate rows and the middleware scope, the therapist endpoints incl. copying, the admin page and endpoints, the built-in catalog keyed by Kinescope video ids and how it is added to each database (admin button or npm run seed-system-templates), the migration.
internal/daily-review.md	Daily Review admin tool. Covers compliance grading (A+ → F), per-patient payload (activity, suggested notes, upcoming + last-completed exercises, flags), the POST /v2/admin/daily-review endpoint, React-PDF rendering pipeline, and how the same service powers the mobile dashboard's Quick Analysis screen.
internal/email-campaigns.md	Email Campaigns admin tool. Covers recipient resolution (tenant + user-type + presets + CSV blending), markdown composer with locale toggle, SendGrid send pipeline with per-recipient NotificationLog writes, and how it differs from Feature Announcements and Notification Management.
messaging.md	Messaging feature overview for web and mobile. Covers who can message whom, one-on-one and group conversations, adding/removing doctors with the "share previous messages" choice, the one-thread-per-group rule, names and role labels, unread badges, loading earlier messages, deep links, push behaviour, and the multiProviderGroupMessaging flag.
patient-therapist-feedback.md	Patient–therapist feedback loop. Covers structured feedback cards in the messages thread, the mobile Session Viewer screen for therapists, the 5-minute debounce window for bundling notes, and the feedbackNotifications feature flag.
internal/exercise-generation.md	Exercise Generation admin tool. Covers the AI pipeline that creates animated exercise demos (GIF/MP4) from a character/limb reference, the async BullMQ queue + worker stages, the admin chat-and-save workflow, the /v2/admin/exercise-generation endpoints, the ExerciseGenerationDraft model, and S3 Spaces / Cloudflare Stream storage.
internal/messaging-architecture.md	Messaging internals. Covers the polling design, the chat data model incl. historyVisibleFrom and indexes, the exact-participant-set identity rule with the advisory lock, membership changes, every /v2/messages endpoint and error code, system-message metadata, the single unread-count query, the web store design, mobile polling and push routing, and known limitations.
internal/feedback-messages.md	Feedback messages internals. Covers the Message.metadata schema, two new MessageType/NotificationType enum values, the feedback-notification BullMQ queue with deterministic-id debouncing, the FeedbackNotificationService flows for both directions, and conversation routing (one-on-one vs group).
internal/decision-models.md	The two structured-decision backends (TypeSafe's Jev via OpenRouter, OpenAI's Decisions API) behind smart search, pairing, custom-tag categories, guideline matching and the live-notes listener: the per-clinic openaiDecisions switch and its no-fallback rule (the AI lab included), which servers can answer, per-backend breakers, environment variables, how OpenAI's request and answer shapes are translated (refusals, incomplete answers), how the two models' probabilities differ and the higher pick gate for OpenAI, cost estimates, the thresholds to re-check, and the BAA/retention check before enabling it.
internal/guidelines-system.md	Guidelines system internals. Covers the data model (documents, sections, recommendations, policies, patient matches, usage), ingestion and extraction, review, applicability matching, the context service every AI feature uses (budgets, precedence, phases, citations), the API, the web UI, seeding the curated library (npm run seed-guidelines) and the guidelines feature flag.
internal/transactional-emails.md	Every email the platform sends: the shared layout (layout.ts) and its blocks, the writing rules, an inventory of the emails with who gets them and where each is built, the preview script and the tests.
internal/password-reset.md	Self-service forgot/reset-password flow. Covers the forgot-password / reset-password endpoints, the bcrypt-hashed one-time token with 1-hour expiry, email-enumeration prevention, refresh-token invalidation, EN/RU email templates, the web flow, and the sign-in that follows a reset.
internal/promotion-campaigns.md	Promotion / promo-code campaigns. Covers the data model (campaign + code + redemption), three redemption sources (SIGNUP / CAMPAIGN_PAGE / PROFILE), JWT-based validate→signup flow, serializable-transaction redemption with maxRedemptions enforcement, getCampaignStats analytics, and the promoCodeCapture tenant feature flag.
internal/sample-patient.md	Sample patient internals. Covers who gets one, containment (no connection, an inert account, opt-in listing), the seeded story (sessions, movement screening from admin-uploaded recordings, video visit), the scripted first-week follow-ups and their notifications, the admin page and its endpoints, the data model and the lifecycle endpoints.