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.
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.
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, usage examples, and the explicitTenantId escape hatch.
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.
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.
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.
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-video-assessment.md	Clinical video assessment for doctors. Covers the mobile recording flow, 3-pass GPT analysis pipeline, Python video processing service, and pose overlay generation.
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.
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.
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, 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.
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/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).