WHOOP Brain – Concussion Recovery Monitoring

Research Background: Active Recovery Over Complete Rest

Traditional concussion treatment has long emphasized complete rest—avoiding physical and cognitive exertion until symptoms resolve. However, emerging research challenges this paradigm.

A 2019 study published in the Clinical Journal of Sports Medicine found that early sub-threshold aerobic exercise significantly hastens recovery from sport-related concussion. The study showed that adolescent athletes who engaged in prescribed aerobic exercise within one week of concussion recovered in an average of 8 days, compared to 24 days for those prescribed rest. Perhaps most striking: 13% of the rest group experienced delayed recovery (>30 days), while none in the exercise group did (Leddy et al., 2019).

The key insight is that controlled physical activity—kept below the symptom exacerbation threshold—can actively promote healing rather than simply waiting for passive recovery.

This application was built to operationalize that research: help athletes recovering from concussion find and maintain their optimal activity level through continuous biometric monitoring and machine learning.

---

What This Application Does

WHOOP Brain is a Node.js application that connects to the WHOOP wearable platform to continuously monitor physiological strain during concussion recovery. It solves the fundamental challenge of active recovery: how do you know when you've done enough activity without doing too much?

Core Workflow

1. Biometric Collection: The app continuously collects data from WHOOP—strain scores, heart rate, workouts, sleep quality, and recovery metrics.

2. Symptom Tracking: Users log their current symptom severity (0-10 scale) through a simple interface.

3. Data Streaming to Foundry: All collected data is automatically streamed to Palantir Foundry for aggregation and analysis.

4. ML-Powered Recommendations: A machine learning model hosted in Foundry analyzes the user's historical patterns and returns:

   • Optimal Strain Target: The recommended activity level for today
   • Predicted Symptoms: Expected symptom severity based on current conditions

5. Real-Time Alerts: As users go about their day, the app monitors their current strain and alerts them when they've reached their optimal target—or warns them if they're exceeding it.

---

Palantir Foundry Integration

The application uses Foundry as its analytics backbone, enabling sophisticated data pipelines and ML inference that would be complex to build standalone.

Data Flow Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   WHOOP API     │────▶│   Node.js App   │────▶│ Foundry Stream  │
│  (biometrics)   │     │                 │     │  (raw events)   │
└─────────────────┘     └────────┬────────┘     └────────┬────────┘
                                 │                       │
                                 │                       ▼
┌─────────────────┐              │              ┌─────────────────┐
│   User Input    │──────────────┘              │ Foundry Dataset │
│  (symptoms)     │                             │  (aggregated)   │
└─────────────────┘                             └────────┬────────┘
                                                         │
       ┌─────────────────────────────────────────────────┘
       ▼
┌─────────────────┐     ┌─────────────────┐
│   Foundry ML    │────▶│   Daily Recs    │
│   Model API     │     │  (optimal strain)│
└─────────────────┘     └─────────────────┘

Foundry Components

Component	Purpose
Datastream	Ingests real-time events (workouts, sleep, recovery, strain readings, symptom submissions)
Pipeline/Dataset	Aggregates and transforms raw events into ML-ready features
ML Model API	Trained model that takes biometric features and outputs personalized strain recommendations

Data Types Sent to Foundry

• strain – Current cycle strain score with heart rate metrics
• workout – Individual workout sessions with duration, type, and strain
• sleep – Sleep episodes with duration and quality scores
• recovery – Daily recovery percentage and HRV data
• day_strain – Finalized daily strain after cycle completes
• symptoms – User-submitted symptom severity ratings

---

Features

• OAuth 2.0 Authentication with WHOOP
• Real-time Strain Monitoring with configurable 10-minute polling
• Webhook Support for instant updates on workout, sleep, and recovery events
• Daily ML Inference with cached results to minimize API calls
• Strain Target Alerts when optimal activity level is reached or exceeded
• Session Management with encrypted token storage in Supabase
• Automatic Token Refresh that survives server restarts

---

Setup

Prerequisites

• Node.js 18+
• A WHOOP developer account with API credentials
• A Supabase account (free tier works)
• Palantir Foundry access with:
  • A streaming dataset configured
  • An inference dataset (aggregated data for ML input)
  • A deployed ML model with API access

1. Install Dependencies

npm install

2. Set Up Supabase Database

Create a free account at supabase.com, create a new project, then run this SQL in the SQL Editor:

CREATE TABLE user_tokens (
  user_id TEXT PRIMARY KEY,
  encrypted_data JSONB NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

3. Configure Environment Variables

Create a .env file in the project root:

# WHOOP API Configuration
CLIENT_ID=your_whoop_client_id
CLIENT_SECRET=your_whoop_client_secret
WHOOP_API_HOSTNAME=https://api.prod.whoop.com

# Server Configuration
PORT=3000
CALLBACK_URL=http://localhost:3000/callback
SESSION_SECRET=your_long_random_session_secret

# Foundry Integration
FOUNDRY_STREAM_URI=your_foundry_stream_uri
FOUNDRY_INFERENCE_URI=your_foundry_inference_dataset_uri
FOUNDRY_MODEL_URI=your_foundry_model_api_uri
FOUNDRY_TOKEN=your_foundry_bearer_token

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key

4. Run the Application

cd Project
node app.js

Visit http://localhost:3000 and authenticate with WHOOP.

---

Usage

1. Connect WHOOP: Click "Connect with WHOOP" to authorize the app
2. Enable Strain Polling: Toggle real-time strain monitoring
3. Log Symptoms: Use the slider to submit how you're feeling (0 = no symptoms, 10 = severe)
4. View Recommendations: The dashboard displays your optimal strain target and predicted symptoms
5. Stay in the Zone: Watch for alerts when you've hit your target—or warnings if you're overdoing it

Disconnect vs. Stay Connected

• Closing the browser: Strain polling and webhook processing continue automatically
• Disconnect WHOOP: Fully revokes access and stops all monitoring

---

API Endpoints

Endpoint	Description
GET /	Dashboard homepage
GET /auth/whoop	Initiate WHOOP OAuth flow
GET /callback	OAuth callback handler
GET /current-strain	Fetch current strain data
POST /submit-symptom	Submit symptom rating
GET /daily-inference	Get ML recommendations (cached daily)
POST /toggle-strain-polling	Enable/disable polling
GET /disconnect	Fully disconnect WHOOP access
POST /webhook	Handle WHOOP webhooks

---

Deployment (Render Free Tier)

The app is optimized for Render's free tier, which spins down after 15 minutes of inactivity but wakes on incoming webhooks.

Pre-Deployment

1. Complete local setup and authenticate with WHOOP first
2. Verify tokens are stored in Supabase

Render Configuration

• Build command: npm install
• Start command: node Project/app.js
• Environment variables: Same as .env above, with CALLBACK_URL updated to your Render URL

The persistent Supabase storage ensures seamless operation across Render's sleep/wake cycles.

---

Security

• Tokens encrypted at rest using AES-256-GCM
• HTTP-only secure cookies in production
• Webhook signature validation
• SSL-encrypted database connections

---

References

• Leddy JJ, Haider MN, Hinds AL, Darling S, Willer BS. A Preliminary Study of the Effect of Early Aerobic Exercise Treatment for Sport-Related Concussion in Males. Clin J Sport Med. 2019;29(5):353-360. PMC6424660