# reem927/recoveryos architecture

> Architecture diagram of the GitHub repository reem927/recoveryos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reem927/recoveryos
- Repository: https://github.com/reem927/recoveryos

## Overview

RecoveryOS is a physical-therapy management platform for practitioners and their clients. Practitioners onboard clinics and manage patient records, then run movement assessments whose scan data is scored into structured findings; session guidance and recovery insights support follow-up care. Clients can join through invitations and use a patient portal. The README documents AI summaries, voice guidance, computer vision, 3D anatomy, and email/Telegram follow-ups. Some subsystem links are based on README statements or the source index; unsampled route internals are not inferred.

Main entry points: [`components/hydrawav3/LegAssessmentScan.tsx`](https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/LegAssessmentScan.tsx) (Movement scan), [`lib/supabase/admin.ts`](https://github.com/reem927/recoveryos/blob/main/lib/supabase/admin.ts) (Supabase records), [`app/api/invites/route.ts`](https://github.com/reem927/recoveryos/blob/main/app/api/invites/route.ts) (Patient invitations), [`app/api/followup/route.ts`](https://github.com/reem927/recoveryos/blob/main/app/api/followup/route.ts) (Follow-up engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_care["Clinical workflow"]
  node_scanui["Movement scan"]
  node_vision["Vision fusion<br/>[vision-fusion.ts]"]
  node_assessment["Assessment scoring"]
  node_validators["Exercise validation"]
  node_anatomy["3D anatomy model<br/>[HumanModel3D.tsx]"]
  node_sessionsetup["Session setup<br/>[page.tsx]"]
  node_protocol["Session protocol"]
  node_sessionclient["Session device client"]
  node_insights["Recovery insights<br/>[page.tsx]"]
  node_summary["Assessment summaries<br/>[route.ts]"]
  node_chat["Recovery assistant<br/>[route.ts]"]
end

subgraph group_patients["Patient experience"]
  node_invite["Patient invitations<br/>[route.ts]"]
  node_clientportal["Client portal<br/>[page.tsx]"]
  node_followup["Follow-up engine<br/>[route.ts]"]
end

subgraph group_platform["Practitioner platform"]
  node_onboarding["Clinic onboarding<br/>[actions.ts]"]
  node_caseload["Patient management<br/>[patients.ts]"]
  node_clientcreate["Add client"]
  node_database[("Supabase records<br/>[admin.ts]")]
  node_appshell["Practitioner interface<br/>[app-shell.tsx]"]
end

subgraph group_services["AI and integrations"]
  node_voice["Sona voice assistant<br/>[sonaVoice.ts]"]
  node_claude["Anthropic Claude"]
  node_email["Email delivery"]
  node_telegram["Telegram notifications<br/>[route.ts]"]
end

node_practitioner(("Practitioner"))

node_practitioner -->|"registers clinic"| node_onboarding
node_practitioner -->|"adds patient"| node_clientcreate
node_clientcreate -.->|"creates record"| node_caseload
node_clientcreate -.->|"submits patient data"| node_database
node_practitioner -->|"invites client"| node_invite
node_invite -->|"updates invite records"| node_database
node_invite -->|"sends invite"| node_email
node_practitioner -->|"runs assessment"| node_scanui
node_scanui -->|"scores movement"| node_assessment
node_scanui -->|"uses vision pipeline"| node_vision
node_scanui -->|"validates exercise"| node_validators
node_scanui -->|"uses voice guidance"| node_voice
node_scanui -->|"renders anatomy"| node_anatomy
node_practitioner -.->|"prepares session"| node_sessionsetup
node_sessionsetup -->|"loads protocol"| node_protocol
node_sessionsetup -->|"configures device"| node_sessionclient
node_sessionclient -->|"uses protocol types"| node_protocol
node_practitioner -->|"reviews recovery"| node_insights
node_insights -->|"uses assessment engine"| node_assessment
node_summary -.->|"reads assessment"| node_database
node_summary -.->|"generates summary"| node_claude
node_practitioner -->|"asks assistant"| node_chat
node_chat -->|"reads and stores messages"| node_database
node_chat -->|"generates reply"| node_claude
node_practitioner -->|"triggers follow-up"| node_followup
node_followup -->|"reads and logs follow-up"| node_database
node_followup -->|"writes message"| node_claude
node_followup -->|"sends follow-up"| node_email
node_practitioner -.->|"notifies practitioner"| node_telegram
node_practitioner -->|"uses workspace"| node_appshell
node_appshell -.->|"supports caseload views"| node_caseload
node_invite -->|"provides join flow"| node_clientportal
node_clientportal -->|"views recovery trends"| node_caseload

click node_onboarding "https://github.com/reem927/recoveryos/blob/main/app/onboarding/actions.ts"
click node_caseload "https://github.com/reem927/recoveryos/blob/main/lib/patients.ts"
click node_clientcreate "https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/add-client-modal.tsx"
click node_invite "https://github.com/reem927/recoveryos/blob/main/app/api/invites/route.ts"
click node_clientportal "https://github.com/reem927/recoveryos/blob/main/app/client/page.tsx"
click node_scanui "https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/LegAssessmentScan.tsx"
click node_vision "https://github.com/reem927/recoveryos/blob/main/lib/vision-fusion.ts"
click node_assessment "https://github.com/reem927/recoveryos/blob/main/lib/leg-assessment-engine.ts"
click node_validators "https://github.com/reem927/recoveryos/blob/main/lib/exercise-validators.ts"
click node_anatomy "https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/HumanModel3D.tsx"
click node_sessionsetup "https://github.com/reem927/recoveryos/blob/main/app/session-setup/page.tsx"
click node_protocol "https://github.com/reem927/recoveryos/blob/main/lib/hydrawav3-protocol.ts"
click node_sessionclient "https://github.com/reem927/recoveryos/blob/main/lib/hydrawav3-client.ts"
click node_insights "https://github.com/reem927/recoveryos/blob/main/app/insights/page.tsx"
click node_summary "https://github.com/reem927/recoveryos/blob/main/app/api/assessments/%5Bid%5D/summarize/route.ts"
click node_chat "https://github.com/reem927/recoveryos/blob/main/app/api/chat/route.ts"
click node_voice "https://github.com/reem927/recoveryos/blob/main/lib/sonaVoice.ts"
click node_followup "https://github.com/reem927/recoveryos/blob/main/app/api/followup/route.ts"
click node_database "https://github.com/reem927/recoveryos/blob/main/lib/supabase/admin.ts"
click node_telegram "https://github.com/reem927/recoveryos/blob/main/app/api/telegram/send/route.ts"
click node_appshell "https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/app-shell.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scanui,node_vision,node_assessment,node_validators,node_anatomy,node_sessionsetup,node_protocol,node_sessionclient,node_insights,node_summary,node_chat toneBlue
class node_invite,node_clientportal,node_followup toneAmber
class node_onboarding,node_caseload,node_clientcreate,node_database,node_appshell toneMint
class node_voice,node_claude,node_email,node_telegram toneRose
class node_practitioner toneIndigo
```

## Components

### Clinical workflow

- [Movement scan](https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/LegAssessmentScan.tsx): `components/hydrawav3/LegAssessmentScan.tsx`
- [Vision fusion](https://github.com/reem927/recoveryos/blob/main/lib/vision-fusion.ts): `lib/vision-fusion.ts`
- [Assessment scoring](https://github.com/reem927/recoveryos/blob/main/lib/leg-assessment-engine.ts): `lib/leg-assessment-engine.ts`
- [Exercise validation](https://github.com/reem927/recoveryos/blob/main/lib/exercise-validators.ts): `lib/exercise-validators.ts`
- [3D anatomy model](https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/HumanModel3D.tsx): `components/hydrawav3/HumanModel3D.tsx`
- [Session setup](https://github.com/reem927/recoveryos/blob/main/app/session-setup/page.tsx): `app/session-setup/page.tsx`
- [Session protocol](https://github.com/reem927/recoveryos/blob/main/lib/hydrawav3-protocol.ts): `lib/hydrawav3-protocol.ts`
- [Session device client](https://github.com/reem927/recoveryos/blob/main/lib/hydrawav3-client.ts): `lib/hydrawav3-client.ts`
- [Recovery insights](https://github.com/reem927/recoveryos/blob/main/app/insights/page.tsx): `app/insights/page.tsx`
- [Assessment summaries](https://github.com/reem927/recoveryos/blob/main/app/api/assessments/%5Bid%5D/summarize/route.ts): `app/api/assessments/[id]/summarize/route.ts`
- [Recovery assistant](https://github.com/reem927/recoveryos/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`

### Patient experience

- [Patient invitations](https://github.com/reem927/recoveryos/blob/main/app/api/invites/route.ts): `app/api/invites/route.ts`
- [Client portal](https://github.com/reem927/recoveryos/blob/main/app/client/page.tsx): `app/client/page.tsx`
- [Follow-up engine](https://github.com/reem927/recoveryos/blob/main/app/api/followup/route.ts): `app/api/followup/route.ts`

### Practitioner platform

- [Clinic onboarding](https://github.com/reem927/recoveryos/blob/main/app/onboarding/actions.ts): `app/onboarding/actions.ts`
- [Patient management](https://github.com/reem927/recoveryos/blob/main/lib/patients.ts): `lib/patients.ts`
- [Add client](https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/add-client-modal.tsx): `components/hydrawav3/add-client-modal.tsx`
- [Supabase records](https://github.com/reem927/recoveryos/blob/main/lib/supabase/admin.ts): `lib/supabase/admin.ts`
- [Practitioner interface](https://github.com/reem927/recoveryos/blob/main/components/hydrawav3/app-shell.tsx): `components/hydrawav3/app-shell.tsx`

### AI and integrations

- [Sona voice assistant](https://github.com/reem927/recoveryos/blob/main/lib/sonaVoice.ts): `lib/sonaVoice.ts`
- **Anthropic Claude**
- **Email delivery**
- [Telegram notifications](https://github.com/reem927/recoveryos/blob/main/app/api/telegram/send/route.ts): `app/api/telegram/send/route.ts`

### Other components

- **Practitioner**

## Connections

- Practitioner → Clinic onboarding: registers clinic
- Practitioner → Add client: adds patient (evidence: `components/hydrawav3/add-client-modal.tsx`)
- Add client → Patient management: creates record
- Add client → Supabase records: submits patient data
- Practitioner → Patient invitations: invites client (evidence: `app/api/invites/route.ts`)
- Patient invitations → Supabase records: updates invite records (evidence: `app/api/invites/route.ts`)
- Patient invitations → Email delivery: sends invite (evidence: `app/api/invites/route.ts`)
- Practitioner → Movement scan: runs assessment
- Movement scan → Assessment scoring: scores movement (evidence: `components/hydrawav3/LegAssessmentScan.tsx`)
- Movement scan → Vision fusion: uses vision pipeline (evidence: `components/hydrawav3/LegAssessmentScan.tsx`)
- Movement scan → Exercise validation: validates exercise (evidence: `components/hydrawav3/LegAssessmentScan.tsx`)
- Movement scan → Sona voice assistant: uses voice guidance (evidence: `components/hydrawav3/LegAssessmentScan.tsx`)
- Movement scan → 3D anatomy model: renders anatomy (evidence: `components/hydrawav3/LegAssessmentScan.tsx`)
- Practitioner → Session setup: prepares session
- Session setup → Session protocol: loads protocol (evidence: `app/session-setup/page.tsx`)
- Session setup → Session device client: configures device (evidence: `app/session-setup/page.tsx`)
- Session device client → Session protocol: uses protocol types (evidence: `lib/hydrawav3-client.ts`)
- Practitioner → Recovery insights: reviews recovery
- Recovery insights → Assessment scoring: uses assessment engine (evidence: `app/insights/page.tsx`)
- Assessment summaries → Supabase records: reads assessment
- Assessment summaries → Anthropic Claude: generates summary
- Practitioner → Recovery assistant: asks assistant
- Recovery assistant → Supabase records: reads and stores messages (evidence: `app/api/chat/route.ts`)
- Recovery assistant → Anthropic Claude: generates reply (evidence: `app/api/chat/route.ts`)
- Practitioner → Follow-up engine: triggers follow-up
- Follow-up engine → Supabase records: reads and logs follow-up (evidence: `app/api/followup/route.ts`)
- Follow-up engine → Anthropic Claude: writes message (evidence: `app/api/followup/route.ts`)
- Follow-up engine → Email delivery: sends follow-up (evidence: `app/api/followup/route.ts`)
- Practitioner → Telegram notifications: notifies practitioner
- Practitioner → Practitioner interface: uses workspace (evidence: `components/hydrawav3/app-shell.tsx`)
- Practitioner interface → Patient management: supports caseload views
- Patient invitations → Client portal: provides join flow
- Client portal → Patient management: views recovery trends (evidence: `app/client/page.tsx`)
