HF-DATASET-SETUP.md

# 🤗 Hugging Face Dataset Setup Guide

## Overview

This server now uses **Hugging Face Dataset** for persistent storage of device tokens instead of local files. This ensures that device data is preserved across Space restarts and provides better data management.

## 🚀 Quick Setup

### 1. Generate Hugging Face Token

1. Go to [Hugging Face Settings](https://huggingface.co/settings/tokens)
2. Click "Create new token"
3. Name: `houzou-notification-server`
4. Type: **Write** (required for dataset operations)
5. Copy the token

### 2. Configure Space Secrets

1. Go to your Space Settings → **Secrets and variables**
2. Add these secrets:

```
HF_TOKEN = hf_your_token_here
HF_DATASET_ID = Detomo/houzou-devices  (optional, defaults to this)
```

### 3. Required Secrets Summary

Your Space needs these secrets:

```
FIREBASE_SERVICE_ACCOUNT = {your firebase config JSON}
HF_TOKEN = hf_your_write_token_here
HF_DATASET_ID = Detomo/houzou-devices (optional)
```

## 📊 Dataset Structure

The dataset will be automatically created with:

```
datasets/Detomo/houzou-devices/
├── README.md           # Dataset documentation
└── devices.json        # Device tokens and metadata
```

### devices.json Format:
```json
[
  [
    "device-id-1",
    {
      "token": "fcm_token_here",
      "lastUpdated": "2024-01-01T00:00:00.000Z",
      "platform": "iOS",
      "appVersion": "1.0.0",
      "registered": true
    }
  ]
]
```

## 🔧 Features

### ✅ Automatic Dataset Management
- Creates dataset if it doesn't exist
- Handles permissions automatically
- Provides fallback to in-memory storage

### ✅ Persistent Storage
- Device tokens survive Space restarts
- Automatic backup to HF dataset
- Version control for device data

### ✅ Error Handling
- Graceful fallback if HF API is unavailable
- Detailed logging for troubleshooting
- Continues operation even if dataset access fails

## 🔍 Verification

### Check Dataset Status
```bash
curl https://your-space-url.hf.space/
```

Response includes:
```json
{
  "message": "Houzou Medical Notification Server",
  "status": "running",
  "hfDataset": {
    "enabled": true,
    "datasetId": "Detomo/houzou-devices",
    "hasToken": true
  },
  "deviceCount": 5
}
```

### View Dataset
1. Go to: https://huggingface.co/datasets/Detomo/houzou-devices
2. Check `devices.json` for your device data

## 🐛 Troubleshooting

### Dataset Not Created
- Verify `HF_TOKEN` has **Write** permissions
- Check Space logs for error messages
- Ensure token is valid and not expired

### Data Not Saving
- Check if HF API is responding
- Verify dataset permissions
- Server will continue with in-memory storage as fallback

### Common Errors

**403 Forbidden**
- Token doesn't have write permissions
- Token is expired or invalid

**404 Not Found**
- Dataset doesn't exist (will be auto-created)
- Wrong dataset ID

**Rate Limiting**
- HF API has rate limits
- Server will retry automatically

## 🔄 Migration from File Storage

If you're migrating from file-based storage:

1. **Backup existing data**: Download your current `devices.json`
2. **Set up HF dataset**: Follow steps above
3. **Deploy updated server**: The server will automatically use HF dataset
4. **Verify**: Check that devices are loaded correctly

## 📋 Environment Variables

```bash
# Required
HF_TOKEN=hf_your_write_token_here
FIREBASE_SERVICE_ACCOUNT={"type":"service_account",...}

# Optional
HF_DATASET_ID=Detomo/houzou-devices
PORT=7860
NODE_ENV=production
```

## 🎯 Benefits

- **✅ Persistent**: Data survives Space restarts
- **✅ Reliable**: Automatic fallback mechanisms
- **✅ Scalable**: No file permission issues
- **✅ Traceable**: Version history in dataset
- **✅ Secure**: Tokens stored in HF infrastructure

## 🔗 Links

- [Hugging Face Hub API](https://huggingface.co/docs/hub/api)
- [Dataset Management](https://huggingface.co/docs/datasets/)
- [Access Tokens](https://huggingface.co/settings/tokens)

---

**Ready to deploy!** Your notification server will now use HF Dataset for persistent storage. 🚀