R3HAB

R3HAB is a hackathon recovery platform for Hydrawav3 workflows. It combines:

• Practitioner-side guided assessment and session tools
• Client-side daily recovery loop with a real-time virtual coach
• ROM tracking, XP/streak gamification, and progress insights
• ElevenLabs voice guidance for coaching cues

What the project does

R3HAB reduces practitioner overhead by moving daily follow-through to an automated client flow while keeping clinical visibility.

Practitioner experience

• Dashboard with session and client workflows
• Guided movement assessment (camera + pose landmarks + wireframe)
• Session orchestration and protocol flow
• Session history and summary endpoints

Client experience

• Recovery Loop page for daily exercise completion
• Virtual Coach that:
• Uses camera pose tracking in real time
• Detects reps and scores quality/correctness
• Requires full-body visibility before starting
• Tracks correct vs wrong reps with visual cues
• Uses voice prompts (ElevenLabs) with throttle logic
• Logs results to daily records and awards XP
• Progress calendar, trend insights, and ROM dashboard (including radar chart)
• Switch-user demo mode (Practitioner + 4 client personas)

Core movement / ROM scope

Implemented ROM-related movements include:

• forward_bend
• squat
• trunk_rotation
• shoulder_flexion

The client daily coach flow currently uses three guided exercise routines:

• Torso rotations
• Leg swings
• Arm rotations

Tech stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind
• Pose tracking: @mediapipe/tasks-vision (browser) + MediaPipe/OpenCV (backend assessment path)
• Backend: FastAPI, Pydantic, Uvicorn
• Data layer: InsForge APIs
• Voice: ElevenLabs Text-to-Speech

Repository structure

R3HAB/
├── frontend/                 # Next.js app (primary UI)
│   ├── src/app/(practitioner)
│   ├── src/app/(client)
│   └── src/components/client/VirtualCoach.tsx
├── backend/                  # FastAPI app
│   └── app/api/v1/endpoints
├── insforge/                 # DB/schema assets
├── docker-compose.yml
└── .env.example

Prerequisites

• Node.js 20+
• npm 10+
• Python 3.11+
• Working webcam (or mobile phone webcam via system camera bridge)

Environment setup

There are two env contexts: backend server env and frontend Next.js env.

1) Backend env

From backend/, create .env:

cd backend
cp ../.env.example .env

Set at least:

• INSFORGE_BASE_URL
• INSFORGE_API_KEY
• HYDRAWAV_BASE_URL
• HYDRAWAV_USERNAME
• HYDRAWAV_PASSWORD
• HYDRAWAV_DEVICE_MAC (optional override)

Optional:

• HUGGINGFACE_API_KEY

2) Frontend env

From frontend/, create .env.local:

cd frontend
cat > .env.local << 'EOF'
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
ELEVENLABS_API_KEY=your_server_side_key_here
ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM
ELEVENLABS_MODEL_ID=eleven_multilingual_v2
EOF

Important:

• NEXT_PUBLIC_API_URL must include /api/v1 for this frontend codebase.
• Voice route (/api/tts) expects ELEVENLABS_API_KEY on the Next.js server runtime.

Install dependencies

Backend

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Frontend

cd frontend
npm install

Run locally

Use two terminals.

Terminal A: backend

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Backend health check:

curl http://localhost:8000/health

Terminal B: frontend

cd frontend
npm run dev

Open:

• http://localhost:3000 (redirects to /recovery)
• Practitioner view: http://localhost:3000/dashboard
• Client recovery loop: http://localhost:3000/recovery

Demo Flow

1. Open /dashboard for practitioner-side view.
2. Use sidebar Switch User to move into a client profile.
3. Open /recovery and enable camera in Virtual Coach.
4. Complete daily exercises to log ROM/XP.
5. Review progress charts and insights.
6. Use "Reset Today's Coach Data" for repeated demo runs.

API highlights

Base prefix: /api/v1

• Assessment:
• POST /assess/video
• POST /assess/mock
• Client loop:
• GET /client/{patient_id}/dashboard
• GET /client/{patient_id}/daily-logs
• POST /client/{patient_id}/daily-game/complete
• POST /client/{patient_id}/daily-game/reset-today
• POST /client/{patient_id}/appointment-request
• Session/protocol/summary routes are also available in backend/app/api/v1/endpoints.

Troubleshooting

AttributeError: module 'mediapipe' has no attribute 'solutions'

This usually indicates an incompatible or broken MediaPipe install. Reinstall backend deps inside the backend venv:

cd backend
source .venv/bin/activate
pip uninstall -y mediapipe
pip install mediapipe==0.10.33

Frontend cannot reach backend

• Confirm backend is running on :8000
• Confirm NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
• Restart npm run dev after env changes

Camera not starting

• Allow browser camera permission
• Ensure no other app is locking the camera
• For phone webcams, confirm the virtual camera appears in browser device list

ElevenLabs TTS not speaking

• Ensure ELEVENLABS_API_KEY is present in frontend/.env.local
• Verify available credits and TTS permission scope on the key
• Check browser console/network for /api/tts errors

Quick quality checks

cd frontend
npx tsc --noEmit

cd backend
source .venv/bin/activate
python -m pip check