🏥 HealthVault

Your Secure Digital Health Locker - Manage, share, and control access to your medical records with ease.

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Getting Started
• Environment Setup
• Database Setup
• API Documentation
• Deployment
• Security
• Contributing
• License

---

🌟 Overview

HealthVault is a modern, secure digital health records management system that empowers patients to:

• Upload and store medical documents securely
• Share records with healthcare providers via OTP or QR code
• Control and revoke access to their medical data
• Track who accessed their records and when

Built with privacy and security at its core, HealthVault uses end-to-end encryption, temporary access tokens, and granular access controls to ensure your medical data remains strictly under your control.

---

✨ Features

👤 Patient Features

• 🔐 Secure Authentication - Email/password login with Supabase Auth
• 📤 Upload Medical Records - Support for PDFs, images (JPG, PNG)
• 🔗 Flexible Sharing Options:
  • OTP-based sharing - Generate 6-digit codes for doctors
  • QR code sharing - Instant access via QR scan
• 🕒 Time-limited Access - All shared access expires automatically
• ❌ Revoke Access - Instantly revoke doctor access at any time
• 📊 Access Logs - View who accessed your records and when
• 🗑️ Delete Records - Permanently remove records from the system
• 📧 Email Notifications - Real-time alerts when records are accessed

👨‍⚕️ Doctor Features

• 🔓 Quick Access - Verify via OTP or QR code scan
• 📱 Mobile-Friendly - QR scanner works on mobile devices
• 📄 View & Download - Access shared medical records
• ⏱️ Session Management - Secure, time-limited access tokens
• 📖 Read-Only Access - View records without modification rights

🔒 Security Features

• 🛡️ Row-Level Security (RLS) - Database-level access control
• 🔑 JWT Authentication - Secure token-based authentication
• 🔐 Encrypted Storage - Files stored in Supabase secure storage
• 📝 Access Logging - Complete audit trail of all record access
• ⏲️ Token Expiration - Auto-expiring access grants (15 minutes for doctors)
• 🚫 No Data Leakage - Signed URLs expire after 1 hour

---

🛠️ Tech Stack

Frontend

• React 19.2 - Modern React with Hooks
• Vite 7.2 - Lightning-fast build tool
• React Router 7.9 - Client-side routing
• Tailwind CSS 3.4 - Utility-first CSS framework
• React Hot Toast - Beautiful toast notifications
• React QR Reader - QR code scanning
• React QR Code - QR code generation

Backend

• Vercel Serverless Functions - API routes
• Supabase - Backend-as-a-Service
  • PostgreSQL database
  • Authentication
  • File storage
  • Row-Level Security (RLS)
• JWT - JSON Web Tokens for doctor sessions
• SendGrid - Email notifications

DevOps

• Vercel - Hosting & CI/CD
• GitHub - Version control
• ESLint - Code linting

---

🏗️ Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Client (React SPA)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Login   │  │Dashboard │  │  Share   │  │  Doctor  │   │
│  │  Signup  │  │  Upload  │  │  Record  │  │  Portal  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Vercel Serverless API Routes                    │
│  /api/upload-record    /api/generate-otp                    │
│  /api/get-records      /api/generate-qr                     │
│  /api/verify-otp       /api/verify-qr                       │
│  /api/revoke-access    /api/log-access                      │
│  /api/delete-record    /api/signed-url                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Supabase Backend                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  PostgreSQL  │  │     Auth     │  │   Storage    │     │
│  │   Database   │  │   (Users)    │  │   (Files)    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  Tables: records, grants, access_logs                       │
└─────────────────────────────────────────────────────────────┘

Database Schema

-- Records table
records (
  id          UUID PRIMARY KEY,
  patient_id  UUID REFERENCES auth.users(id),
  title       TEXT,
  description TEXT,
  file_url    TEXT,
  uploaded_at TIMESTAMP
)

-- Access grants table
grants (
  id           UUID PRIMARY KEY,
  patient_id   UUID REFERENCES auth.users(id),
  doctor_email TEXT,
  otp_hash     TEXT,
  qr_token     TEXT,
  expires_at   TIMESTAMP,
  is_active    BOOLEAN,
  records      JSONB,
  created_at   TIMESTAMP
)

-- Access logs table
access_logs (
  id          UUID PRIMARY KEY,
  grant_id    UUID REFERENCES grants(id),
  doctor_id   TEXT,
  record_id   UUID REFERENCES records(id),
  accessed_at TIMESTAMP
)

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Supabase account (supabase.com)
• Vercel account (for deployment)

Installation

1. Clone the repository

git clone https://github.com/Th-Shivam/HealthVault.git
cd HealthVault

2. Install dependencies

npm install --legacy-peer-deps

3. Set up environment variables

Create a .env file in the root directory:

# Frontend (Vite)
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

# Backend (Serverless functions)
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Email Notifications (SendGrid)
SENDGRID_API_KEY=your_sendgrid_api_key_here

4. Set up Supabase database

Run the SQL commands in supabase_setup.sql:

# Copy the contents of supabase_setup.sql
# Paste and execute in Supabase SQL Editor

5. Run development server

# For frontend only
npm run dev

# For full-stack (API routes + frontend)
npx vercel dev

6. Access the application

http://localhost:3000

---

🔧 Environment Setup

Supabase Configuration

1. Create a new project at supabase.com
2. Navigate to Settings → API
3. Copy the following values:
   • Project URL → VITE_SUPABASE_URL and SUPABASE_URL
   • Anon/Public Key → VITE_SUPABASE_ANON_KEY
   • Service Role Key → SUPABASE_SERVICE_ROLE_KEY ⚠️ (Keep this secret!)

Storage Bucket Setup

1. Go to Storage in Supabase dashboard
2. Create a new bucket named medical-records
3. Set it to Public (for now) or configure RLS policies
4. Note: For production, use private buckets with signed URLs

SendGrid Configuration (Optional but Recommended)

1. Create a free account at sendgrid.com
2. Verify your sender email address
3. Navigate to Settings → API Keys
4. Create a new API key with Full Access permissions
5. Copy the API key to your .env file as SENDGRID_API_KEY
6. Important: Replace noreply@healthvault.app in api/services/email-service.js with your verified sender email

Note: Without SendGrid configured, the app will work perfectly but email notifications will be skipped.

---

💾 Database Setup

Execute the following SQL in your Supabase SQL Editor:

# Run the complete setup script
cat supabase_setup.sql | supabase db reset

This creates:

• ✅ records table with RLS policies
• ✅ grants table with RLS policies
• ✅ access_logs table with RLS policies
• ✅ medical-records storage bucket
• ✅ Storage policies for authenticated uploads

---

📡 API Documentation

Patient APIs

POST /api/upload-record

Upload a medical record.

Request:

{
  "patient_id": "uuid",
  "title": "Blood Test Report",
  "description": "Annual checkup",
  "file": "base64_encoded_file",
  "file_name": "report.pdf"
}

Response:

{
  "success": true,
  "record_id": "uuid"
}

POST /api/generate-otp

Generate OTP for sharing records.

Request:

{
  "patient_id": "uuid",
  "doctor_email": "doctor@example.com",
  "record_ids": ["uuid1", "uuid2"]
}

Response:

{
  "success": true,
  "otp": "123456"
}

POST /api/generate-qr

Generate QR code token for sharing.

Request:

{
  "patient_id": "uuid",
  "record_ids": ["uuid1", "uuid2"]
}

Response:

{
  "success": true,
  "qr_token": "signed_token_string"
}

POST /api/revoke-access

Revoke doctor access to records.

Request:

{
  "grant_id": "uuid"
}

Response:

{
  "success": true
}

POST /api/delete-record

Delete a medical record (requires auth).

Headers:

Authorization: Bearer <supabase_access_token>

Request:

{
  "record_id": "uuid",
  "file_path": "path/to/file",
  "patient_id": "uuid"
}

Response:

{
  "success": true,
  "message": "Record deleted successfully"
}

Doctor APIs

POST /api/verify-otp

Verify OTP and get access token.

Request:

{
  "doctor_email": "doctor@example.com",
  "otp": "123456"
}

Response:

{
  "success": true,
  "token": "jwt_access_token"
}

POST /api/verify-qr

Verify QR token and get access.

Request:

{
  "qr_token": "signed_token_string"
}

Response:

{
  "success": true,
  "token": "jwt_access_token"
}

POST /api/get-records

Get shared medical records (requires doctor JWT).

Headers:

Authorization: Bearer <doctor_jwt_token>

Response:

{
  "success": true,
  "records": [
    {
      "id": "uuid",
      "title": "Blood Test",
      "description": "Annual checkup",
      "file_url": "original_url",
      "signed_url": "signed_url_with_token",
      "uploaded_at": "2024-01-01T00:00:00Z"
    }
  ],
  "grant_id": "uuid",
  "doctor_email": "doctor@example.com"
}

POST /api/log-access

Log when a doctor views a record.

Request:

{
  "grant_id": "uuid",
  "doctor_id": "doctor@example.com",
  "record_id": "uuid"
}

Response:

{
  "success": true
}

---

🌐 Deployment

Deploy to Vercel

1. Install Vercel CLI

npm install -g vercel

2. Link your project

vercel link

3. Set environment variables in Vercel

   • Go to your project settings on vercel.com
   • Add all environment variables from .env

4. Deploy

git push origin main
# Vercel auto-deploys on push

Build Configuration

The project uses the following build settings:

• Framework: Vite
• Build Command: npm run build
• Output Directory: dist
• Install Command: npm install --legacy-peer-deps

---

🔒 Security

Best Practices Implemented

✅ Authentication & Authorization

• Supabase Auth for patient login
• JWT tokens for doctor sessions
• Row-Level Security (RLS) on all tables

✅ Data Protection

• Encrypted file storage
• Signed URLs with expiration
• OTP hashing (SHA-256)
• HMAC-signed QR tokens

✅ Access Control

• Temporary access grants (15 min for doctors)
• Manual revocation capability
• Audit logging for all access

✅ API Security

• CORS headers configured
• Input validation
• Error handling without data leakage

Security Considerations

⚠️ For Production

1. Use a dedicated JWT secret (not Supabase service key)
2. Set storage bucket to private
3. Implement rate limiting
4. Add CAPTCHA to signup/login
5. Enable MFA for patient accounts
6. Regular security audits

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Write meaningful commit messages
• Add comments for complex logic
• Test your changes thoroughly
• Update documentation as needed

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👥 Authors

• Shivam - @Th-Shivam

---

🙏 Acknowledgments

• Supabase - Backend infrastructure
• Vercel - Hosting platform
• Tailwind CSS - UI framework
• React - Frontend framework

---

📧 Support

For support, email support@healthvault.com or open an issue on GitHub.

---

Made with ❤️ for better healthcare

Report Bug · Request Feature