FRONTEND_CONNECTION_GUIDE.md

# 🚀 Frontend Connection to Hugging Face Backend

## ✅ Configuration Complete!

Your Next.js frontend is now configured to connect to your Hugging Face Space backend.

---

## 📋 Changes Made

### 1. ✅ Frontend Environment Configuration

**Created:** [`frontend/.env.local`](frontend/.env.local)

```env
NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space
INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space
```

This tells the frontend where to find your deployed backend API.

### 2. ✅ API Client Already Configured

**File:** [`frontend/src/lib/api/client.ts`](frontend/src/lib/api/client.ts)

The API client already uses dynamic configuration:
- ✅ Reads from `process.env.NEXT_PUBLIC_API_URL`
- ✅ Falls back to auto-detection
- ✅ Ultimate fallback to `http://127.0.0.1:5055`

**No changes needed!** The existing code will automatically use your `.env.local` settings.

### 3. ✅ CORS Configuration Updated

**File:** [`api/main.py`](api/main.py)

Updated CORS to allow requests from:
- ✅ `http://localhost:3000` (local development)
- ✅ `http://127.0.0.1:3000` (local development)
- ✅ `https://baveshraam-open-notebook.hf.space` (your HF Space)
- ✅ `*` (wildcard - allows any origin)

### 4. ✅ Hardcoded URLs Checked

All hardcoded `localhost:5055` references in the frontend are:
- ✅ **Fallback defaults only** (when env vars not set)
- ✅ **Example text in error messages** (documentation)
- ✅ **No action needed** - proper fallback behavior

---

## 🎯 Next Steps

### Step 1: Deploy Backend Changes to Hugging Face

The CORS update needs to be deployed to your Hugging Face Space:

```bash
git add api/main.py
git commit -m "Update CORS for frontend connection"
git push
```

Wait for Hugging Face to rebuild (check the Space logs).

### Step 2: Start Your Frontend Locally

```bash
cd frontend
npm install  # If not already done
npm run dev
```

Your frontend will start on `http://localhost:3000` and connect to:
- **Backend API:** `https://baveshraam-open-notebook.hf.space`

### Step 3: Test the Connection

1. **Open browser:** http://localhost:3000
2. **Check browser console** for API connection messages
3. **Try creating a notebook** or any API-dependent feature
4. **Check Network tab** to verify requests go to your HF Space URL

---

## 🔍 How It Works

### Configuration Priority

The frontend uses a smart fallback system:

```
1. Runtime config from /config endpoint (uses .env.local)
   ↓
2. Build-time NEXT_PUBLIC_API_URL
   ↓
3. Auto-detection from browser URL
   ↓
4. Fallback to http://127.0.0.1:5055
```

### Environment Variables

| Variable | Used By | Purpose |
|----------|---------|---------|
| `NEXT_PUBLIC_API_URL` | Browser | Client-side API calls |
| `INTERNAL_API_URL` | Next.js Server | Server-side proxying |

### URL Structure

The frontend automatically constructs API URLs:

- Base URL: `https://baveshraam-open-notebook.hf.space`
- API Endpoint: `/api` (added automatically)
- Full API URL: `https://baveshraam-open-notebook.hf.space/api`

---

## 🛠️ Troubleshooting

### Issue: "Failed to fetch" or CORS errors

**Solution:**
1. Verify backend is running: https://baveshraam-open-notebook.hf.space/health
2. Check backend logs for CORS rejections
3. Ensure CORS changes were deployed (check git commit)

### Issue: Frontend still connects to localhost

**Solution:**
1. Verify `.env.local` file exists in `frontend/` directory
2. Restart Next.js dev server: `npm run dev`
3. Check browser console for config messages
4. Clear browser cache and reload

### Issue: 404 errors on /api/* endpoints

**Solution:**
1. Check that backend is running: https://baveshraam-open-notebook.hf.space/api/config
2. Verify the URL doesn't have double `/api/api/`
3. Check Next.js rewrite configuration in `next.config.ts`

---

## 📝 Environment Files Reference

### `.env.local` (active configuration)
Your current deployment settings.

### `.env.local.example` (template)
Copy this when deploying to new environments.

### `.env.example` (backend configuration)
Backend environment variables (already configured on HF Space).

---

## 🎉 Success Indicators

You'll know the connection works when:

1. ✅ Browser console shows: `✅ [Config] Successfully loaded API config`
2. ✅ Network tab shows requests to `baveshraam-open-notebook.hf.space`
3. ✅ No CORS errors in browser console
4. ✅ Features like "Create Notebook" work correctly
5. ✅ Health check responds: https://baveshraam-open-notebook.hf.space/health

---

## 🚀 Deploy Frontend (Optional)

When ready to deploy your frontend:

### Vercel / Netlify
Add environment variables in dashboard:
```
NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space
INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space
```

### Docker
```bash
docker build -t open-notebook-frontend ./frontend
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space \
  -e INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space \
  open-notebook-frontend
```

---

## 📚 Architecture Overview

```
┌─────────────────────┐
│   Browser           │
│   localhost:3000    │
└──────────┬──────────┘
           │ NEXT_PUBLIC_API_URL
           ↓
┌─────────────────────────────────────┐
│   Hugging Face Space Backend        │
│   baveshraam-open-notebook.hf.space │
│                                     │
│   ┌──────────┐      ┌──────────┐  │
│   │ FastAPI  │ ←──→ │ SurrealDB│  │
│   └──────────┘      └──────────┘  │
└─────────────────────────────────────┘
```

---

## 🎊 You're All Set!

Your frontend is now ready to connect to your Hugging Face deployed backend. Start the frontend with `npm run dev` and test away!