Skip to main content

​
Prerequisites

Before you begin, make sure you have:
The application uses Claude Sonnet 4 for all AI-powered features.

​
Installation

1

Clone and Install Dependencies

Clone the repository and install all required packages:
git clone <repository-url>
cd handoff
npm install
This will install all frontend and backend dependencies including:
  • React 18 and Vite for the frontend
  • Express.js for the backend API
  • Anthropic SDK for Claude AI integration
  • Supabase client for authentication and database
2

Set Up Supabase Database

Create a new Supabase project and set up the required tables:

​
Create Database Tables

Run these SQL commands in your Supabase SQL Editor:
-- Patients table
CREATE TABLE patients (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  patient_id TEXT UNIQUE,
  mrn TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  age INTEGER,
  sex TEXT,
  diagnosis TEXT,
  condition TEXT,
  risk_level TEXT DEFAULT 'medium',
  code_status TEXT DEFAULT 'Full Code',
  medications JSONB DEFAULT '[]',
  allergies JSONB DEFAULT '[]',
  admission_date TIMESTAMPTZ,
  last_vitals JSONB DEFAULT '{}',
  handoff_notes TEXT,
  image_analysis TEXT,
  last_handoff_update TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Nurses table
CREATE TABLE nurses (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  auth_user_id UUID UNIQUE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Rooms table
CREATE TABLE rooms (
  id TEXT PRIMARY KEY,
  patient_id UUID REFERENCES patients(id),
  grid_x INTEGER DEFAULT 0,
  grid_y INTEGER DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Tasks table
CREATE TABLE tasks (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  patient_id UUID REFERENCES patients(id),
  room_id TEXT REFERENCES rooms(id),
  time TEXT NOT NULL,
  type TEXT NOT NULL,
  description TEXT NOT NULL,
  priority TEXT DEFAULT 'medium',
  completed BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Room assignments table
CREATE TABLE room_assignments (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  room_id TEXT REFERENCES rooms(id),
  nurse_id UUID REFERENCES nurses(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
These tables support real-time subscriptions. The application automatically refreshes when data changes.
3

Configure Environment Variables

Copy the example environment file and add your credentials:
cp .env.example .env
Edit .env and add your configuration:
# Server Port
PORT=3001
Security Note: API keys are server-side only and NEVER exposed to the browser. The backend server proxies all AI requests securely.
4

Create Nurse Accounts

Add nurses to your database and create authentication accounts:

​
Option 1: Manually Add Nurses

Insert nurse records in your Supabase SQL Editor:
INSERT INTO nurses (email, name) VALUES
  ('nurse1@hospital.com', 'Jane Smith'),
  ('nurse2@hospital.com', 'John Doe');

​
Option 2: Create Auth Accounts

After adding nurses to the database, create Supabase Auth accounts for them:
# Start the server first
npm run server

# In another terminal, create auth accounts
curl -X POST http://localhost:3001/api/nurses/create-accounts
This endpoint will:
  • Create Supabase Auth accounts for all nurses in your database
  • Link auth users to nurse records via auth_user_id
  • Return temporary passwords for each created account
  • Skip nurses that already have accounts
The temporary passwords should be changed on first login. The endpoint requires SUPABASE_SERVICE_KEY in your .env file.
5

Start the Application

Start both the backend server and frontend development server:
npm start
This runs both services concurrently:
You can also run them separately with npm run server and npm run dev in different terminals.

​
Verify Everything is Working

Check the server status:
curl http://localhost:3001/api/health
You should see:
{
  "status": "ok",
  "availableProviders": {
    "claude": true,
    "supabase": true
  }
}

​
Generate Your First Handoff Note

Now let’s create your first AI-powered handoff note!
1

Log In

  1. Open http://localhost:5173 in your browser
  2. Log in with a nurse account email and password
  3. You’ll be redirected to the dashboard
Use the email and temporary password from the account creation step.
2

View Patient List

From the dashboard:
  1. Click on any patient card to open their detailed view
  2. You’ll see:
    • Patient demographics and vital signs
    • Medication list and allergies
    • Tasks and their completion status
    • Previous handoff notes (if any)
If you don’t see any patients, you’ll need to add patient data to your Supabase patients table first.
3

Generate Handoff Notes from Record

In the patient detail view:
  1. Click “Generate from Record”: The AI will analyze the patient data
  2. Wait for Generation: Takes 3-5 seconds
  3. Review the Notes: Claude AI generates structured handoff including:
    • Patient overview and shift forecast
    • Current clinical status and vital signs
    • Key lab/imaging findings and trends
    • Active medications and treatments
    • Task status (completed vs. outstanding)
    • Safety concerns and alerts
Patient Data Flow
// Real API endpoint from server/index.js:145
POST /api/summarize-record/claude

// Request body
{
  "patientData": {
    "name": "John Doe",
    "age": 65,
    "medications": ["Metformin", "Lisinopril"],
    "tasks": [
      { "time": "08:00", "description": "Vitals check", "completed": true },
      { "time": "12:00", "description": "Blood draw", "completed": false }
    ]
  },
  "previousNotes": "...",  // Optional: for change tracking
  "imageAnalysis": "..."   // Optional: from whiteboard image
}
The AI uses Claude Sonnet 4 (claude-sonnet-4-20250514) which excels at medical terminology and trend analysis.
4

Upload Handoff Image (Optional)

To enhance your handoff with whiteboard or document images:
  1. Click “Upload Handoff Image”
  2. Select an image: JPG, PNG, or other image format (max 10MB)
  3. Analyze: The AI extracts information from the image
  4. Merge: Click “Generate from Record” again to combine image analysis with patient data
Image Analysis Flow
// Real API endpoint from server/index.js:63
POST /api/analyze-image/claude

// Multipart form data with image file
Content-Type: multipart/form-data

// AI extracts:
// - Vital signs from whiteboard
// - Handwritten notes and orders
// - Task lists and checkboxes
// - Safety alerts and warnings
Image information is automatically integrated into the appropriate sections, not listed separately. The AI merges image data with the electronic record intelligently.
5

Edit and Save

Customize the AI-generated notes:
  1. Click “Edit”: Opens the notes in edit mode
  2. Make Changes: Add clinical judgment, clarify details, or update information
  3. Click “Save”: Stores notes to the patient record
  4. Copy: Use the “Copy” button to share with your team
Save Handoff Notes
// Real API endpoint from server/index.js:469
POST /api/patients/:mrn/handoff

// Request body
{
  "handoffNotes": "## Patient Overview\n...",
  "imageAnalysis": "Whiteboard shows...",
  "timestamp": "2024-03-04T10:30:00Z"
}
The handoff notes are saved with:
  • Current timestamp for version tracking
  • Both handoff notes and image analysis (if provided)
  • Automatic update to updated_at field

​
Real Usage Example

Here’s how the components work together: 
// Real-time patient data subscription
const channel = supabase
  .channel('rooms-changes')
  .on('postgres_changes', {
    event: '*',
    schema: 'public',
    table: 'patients'
  }, () => {
    fetchRooms(); // Auto-refresh on changes
  })
  .subscribe();

​
Key API Endpoints Reference

These are the main endpoints you’ll interact with:
EndpointMethodDescription
/api/healthGETCheck server status and available AI providers
/api/analyze-image/claudePOSTAnalyze handoff whiteboard/document image with Claude
/api/summarize-record/claudePOSTGenerate handoff notes from patient record with Claude
/api/patientsGETGet all patient records with room and task info
/api/patients/:idGETGet single patient record by MRN
/api/patients/:id/handoffPOSTSave handoff notes for a patient
/api/patients/:idPATCHUpdate patient information
/api/tasks/:idPATCHUpdate task completion status
/api/nursesGETGet all nurses
/api/nurses/create-accountsPOSTCreate Supabase Auth accounts for nurses
All endpoints run on http://localhost:3001 by default. Change the port with the PORT environment variable.

​
Troubleshooting

​
”API is not configured” Error

Make sure you have added your Anthropic API key to your .env file: 
ANTHROPIC_API_KEY=sk-ant-...
Restart the server after adding the key: 
npm run server

​
Server Not Starting

Check if port 3001 is already in use: 
# On macOS/Linux
lsof -i :3001

# Change the port in .env if needed
PORT=3002

​
Images Not Analyzing

Ensure your image:
  • Is under 10MB (file size limit)
  • Is in a supported format (JPG, PNG, WebP, etc.)
  • Contains visible text or information

​
No Patients Showing

Add sample patient data to your Supabase database: 
INSERT INTO patients (mrn, name, age, sex, diagnosis, condition, risk_level) VALUES
  ('MRN001', 'John Doe', 65, 'M', 'CHF', 'Stable', 'medium'),
  ('MRN002', 'Jane Smith', 72, 'F', 'Pneumonia', 'Improving', 'high');

INSERT INTO rooms (id, patient_id, grid_x, grid_y) VALUES
  ('101', (SELECT id FROM patients WHERE mrn = 'MRN001'), 0, 0),
  ('102', (SELECT id FROM patients WHERE mrn = 'MRN002'), 1, 0);

​
Next Steps

Now that you’ve generated your first handoff note, explore more features:
  • Task Management: Mark tasks as completed from the patient detail view
  • Route Planning: Use the Route view to optimize your rounds
  • Team Coordination: View nurse assignments in the Schedule view
  • Activity Logs: Track all system events in the Logs view
  • Risk Filtering: Filter patients by risk level (critical, high, medium, low)
  • My Patients View: Toggle to see only your assigned patients

API Documentation

Explore all available API endpoints and request/response formats.

Features Guide

Learn about all the features and capabilities of Nurse Handoff Helper.

Build docs developers (and LLMs) love

Get started for freeTalk to us