Supabase Setup

Overview

The Nurse Handoff Helper uses Supabase as its database and authentication backend. This guide walks through setting up your Supabase project and configuring the required database tables.

Supabase provides a free tier that’s perfect for development and small-scale deployments. Visit supabase.com to create an account.

Create a Supabase Project

Go to supabase.com and sign up or log in
Click New Project
Choose your organization
Configure your project:
- Name: nurse-handoff-helper (or your preferred name)
- Database Password: Generate a secure password and save it
- Region: Choose the region closest to your users
- Pricing Plan: Start with the free tier
Click Create new project

Wait a few minutes for Supabase to provision your database.

Get Your API Keys

Once your project is ready:

Go to Project Settings (gear icon in the sidebar)
Navigate to API section
Copy the following values to your .env file:
- Project URL → VITE_SUPABASE_URL and SUPABASE_URL
- anon public key → VITE_SUPABASE_ANON_KEY and SUPABASE_ANON_KEY
- service_role key → SUPABASE_SERVICE_KEY

Keep your service_role key secret! It bypasses Row Level Security and should never be exposed to the frontend.

Database Schema

The application requires the following database tables. You can create them using the Supabase SQL Editor.

Required Tables

Stores patient information and medical records.

CREATE TABLE patients (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  patient_id VARCHAR UNIQUE,
  name VARCHAR NOT NULL,
  mrn VARCHAR UNIQUE NOT NULL,
  age INTEGER,
  sex VARCHAR,
  diagnosis TEXT,
  condition TEXT,
  risk_level VARCHAR DEFAULT 'medium',
  code_status VARCHAR 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()
);

Stores nurse profiles and authentication information.

CREATE TABLE nurses (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  auth_user_id UUID UNIQUE REFERENCES auth.users(id),
  name VARCHAR NOT NULL,
  email VARCHAR UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

Stores hospital room information and patient assignments.

CREATE TABLE rooms (
  id VARCHAR 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()
);

Stores nursing tasks and their completion status.

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

Links nurses to their assigned rooms.

CREATE TABLE room_assignments (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  room_id VARCHAR REFERENCES rooms(id),
  nurse_id UUID REFERENCES nurses(id),
  assigned_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(room_id, nurse_id)
);

Stores activity logs for audit purposes.

CREATE TABLE logs (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  nurse VARCHAR,
  room VARCHAR,
  action VARCHAR NOT NULL,
  details TEXT,
  time TIMESTAMPTZ DEFAULT NOW()
);

Enable Realtime

The application uses Supabase Realtime for live updates. Enable it for the required tables:

Go to Database → Replication in your Supabase dashboard
Enable replication for these tables:
- patients
- nurses
- rooms
- tasks
- room_assignments
- logs

Realtime enables the application to show live updates when data changes, such as when tasks are completed or patient information is updated.

Row Level Security (RLS)

For security, enable Row Level Security on all tables:

-- Enable RLS
ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
ALTER TABLE nurses ENABLE ROW LEVEL SECURITY;
ALTER TABLE rooms ENABLE ROW LEVEL SECURITY;
ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
ALTER TABLE room_assignments ENABLE ROW LEVEL SECURITY;
ALTER TABLE logs ENABLE ROW LEVEL SECURITY;

Then create policies for authenticated users:

-- Example: Allow authenticated nurses to read all patients
CREATE POLICY "Nurses can view all patients"
  ON patients FOR SELECT
  TO authenticated
  USING (true);

-- Example: Allow authenticated nurses to update patients
CREATE POLICY "Nurses can update patients"
  ON patients FOR UPDATE
  TO authenticated
  USING (true)
  WITH CHECK (true);

-- Add similar policies for other tables

Customize RLS policies based on your security requirements. You may want to restrict certain operations to specific nurse roles.

Authentication Setup

The application uses Supabase Auth for nurse login:

Go to Authentication → Providers in Supabase
Ensure Email is enabled
Configure email templates if desired (optional)
Under Settings:
- Set Site URL to your application URL (e.g., http://localhost:5173 for dev)
- Add redirect URLs if needed

Supabase Client Configuration

The application initializes two Supabase clients:

Frontend Client

Used by the React application (src/lib/supabase.js:13):

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    persistSession: true,
    autoRefreshToken: true,
    detectSessionInUrl: true
  }
});

Backend Client

Used by the Express server (server/index.js:32):

// Regular client for general operations
const supabase = createClient(
  process.env.SUPABASE_URL || "",
  process.env.SUPABASE_SERVICE_KEY || process.env.SUPABASE_ANON_KEY || ""
);

// Admin client for user management operations
const supabaseAdmin = process.env.SUPABASE_SERVICE_KEY
  ? createClient(
      process.env.SUPABASE_URL || "",
      process.env.SUPABASE_SERVICE_KEY,
      {
        auth: {
          autoRefreshToken: false,
          persistSession: false,
        },
      }
    )
  : null;

Verify Setup

Test your Supabase connection:

# Start the development server
npm run dev

# In another terminal, check if Supabase is connected
curl http://localhost:3001/api/health

You should see:

{
  "status": "ok",
  "availableProviders": {
    "claude": true,
    "supabase": true
  }
}

Troubleshooting

Connection refused or timeout errors

Verify your SUPABASE_URL is correct and includes https://
Check that your Supabase project is not paused (free tier pauses after inactivity)
Ensure your API keys are correct and not expired

Authentication errors

Verify SUPABASE_ANON_KEY is correctly set
Check that Row Level Security policies allow the operation
Ensure the user is authenticated when required

Admin operations fail

Verify SUPABASE_SERVICE_KEY is set correctly
This key is required for creating nurse accounts and admin operations
Never use the service key in frontend code

Next Steps

After setting up Supabase:

Create nurse accounts - see Nurse Accounts
Populate initial data (optional)
Start the application with npm start

Get Started

Setup

Features

User Guide

Overview

Create a Supabase Project

Get Your API Keys

Database Schema

Required Tables

Enable Realtime

Row Level Security (RLS)

Authentication Setup

Supabase Client Configuration

Frontend Client

Backend Client

Verify Setup

Troubleshooting

Next Steps

Build docs developers (and LLMs) love

Get Started

Setup

Features

User Guide

​Overview

​Create a Supabase Project

​Get Your API Keys

​Database Schema

​Required Tables

​Enable Realtime

​Row Level Security (RLS)

​Authentication Setup

​Supabase Client Configuration

​Frontend Client

​Backend Client

​Verify Setup

​Troubleshooting

​Next Steps

Build docs developers (and LLMs) love

Overview

Create a Supabase Project

Get Your API Keys

Database Schema

Required Tables

Enable Realtime

Row Level Security (RLS)

Authentication Setup

Supabase Client Configuration

Frontend Client

Backend Client

Verify Setup

Troubleshooting

Next Steps