HUGGING_FACE_SETUP.md

# 🚀 Domify Academy Super Bot - Hugging Face Setup Guide

## Download Backend Code

**Download the complete backend code package:**

📦 **[Download backend-code.tar.gz](https://files.manuscdn.com/user_upload_by_module/session_file/310519663512731124/PptOqCfNfXiULWvx.gz)**

---

## What's Included

The archive contains all backend files:

```
backend-code/
├── server/
│   ├── llm.ts                 # LLM engine with NVIDIA integration
│   ├── search.ts              # DuckDuckGo search
│   ├── rateLimit.ts           # Rate limiting middleware
│   ├── db.ts                  # Database helpers
│   ├── googleSheets.ts        # Google Sheets logging
│   ├── middleware.ts          # Industrial middleware
│   ├── routers.ts             # tRPC procedures
│   ├── storage.ts             # S3 storage helpers
│   └── auth.logout.test.ts    # Test example
├── drizzle/
│   └── schema.ts              # Database schema
├── Dockerfile                 # Production Docker image
├── DEPLOYMENT.md              # Complete deployment guide
├── BACKEND_README.md          # Backend documentation
├── QUICKSTART.md              # 5-minute quick start
└── .dockerignore              # Docker build optimization
```

---

## Step-by-Step Setup

### Step 1: Extract Files

```bash
# Extract the archive
tar -xzf backend-code.tar.gz

# You now have all the files
ls -la
```

### Step 2: Create Hugging Face Space

1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click **"Create new Space"**
3. Fill in:
   - **Space name**: `domify-academy-bot`
   - **SDK**: Select **"Docker"**
   - **License**: Apache 2.0
   - **Visibility**: Public
4. Click **"Create Space"**

### Step 3: Get Your Repository URL

After creating, you'll see:
```
https://huggingface.co/spaces/YOUR_USERNAME/domify-academy-bot
```

### Step 4: Copy Files to Hugging Face

```bash
# Initialize git in your local directory
cd /path/to/extracted/files
git init

# Add all files
git add .

# Commit
git commit -m "Domify Academy Bot - Backend"

# Add Hugging Face remote
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/domify-academy-bot

# Push to Hugging Face
git push -u origin main
```

### Step 5: Set Environment Variables

In Hugging Face Space **Settings** → **Repository secrets**, add:

| Variable | Value | Example |
|----------|-------|---------|
| `DATABASE_URL` | MySQL connection | `mysql://user:pass@host/db` |
| `NVIDIA_API_KEY` | Your NVIDIA key | `nvapi-xxxxx` |
| `JWT_SECRET` | Random secret | `openssl rand -base64 32` |

**Optional:**
- `GOOGLE_SHEETS_API_KEY` - For feedback logging
- `GOOGLE_SHEETS_ID` - Google Sheet ID

### Step 6: Wait for Build

Hugging Face will:
1. Detect the `Dockerfile`
2. Build the image (5-10 minutes)
3. Deploy automatically
4. Assign a public URL

**Monitor in the "Build" tab**

### Step 7: Test

Once deployed:

```bash
# Test health endpoint
curl https://YOUR_SPACE_URL/api/health

# Expected response:
{
  "status": "healthy",
  "uptime": 123.45,
  "database": "connected"
}
```

---

## File Descriptions

### `server/llm.ts`
LLM engine with NVIDIA API integration. Handles:
- Llama-3 70B as primary model
- Automatic fallback to alternate models
- DeepSeek-style reasoning generation
- Image generation via SDXL/Flux

### `server/search.ts`
DuckDuckGo search integration for "Search Online" mode.

### `server/rateLimit.ts`
Token bucket rate limiting to prevent API abuse.

### `server/db.ts`
Database helper functions for:
- User management
- Conversation history
- Message storage
- Image management
- Feedback logging

### `server/googleSheets.ts`
Google Sheets integration for feedback analytics.

### `server/middleware.ts`
Industrial-standard middleware:
- Request logging
- Response caching
- Error handling
- Performance monitoring
- Security headers

### `server/routers.ts`
tRPC procedure definitions:
- `chat.send` - Text generation
- `imagine.generate` - Image generation
- `search.online` - Web search

### `drizzle/schema.ts`
Database schema with tables:
- `users` - User accounts
- `conversations` - Chat conversations
- `messages` - Individual messages
- `images` - Generated images
- `feedback` - User feedback

### `Dockerfile`
Production-ready Docker image for Hugging Face Spaces.

### `DEPLOYMENT.md`
Complete deployment guide with troubleshooting.

### `BACKEND_README.md`
Backend API documentation and reference.

### `QUICKSTART.md`
5-minute quick start guide.

---

## Environment Variables Reference

### Required

**`DATABASE_URL`**
- Format: `mysql://user:password@host:port/database`
- Example: `mysql://admin:secret@db.example.com:3306/domify_bot`
- Get from: Your database provider

**`NVIDIA_API_KEY`**
- Get from: [NVIDIA Build Portal](https://build.nvidia.com/)
- Used for: Llama-3 70B, SDXL, Flux models

**`JWT_SECRET`**
- Generate: `openssl rand -base64 32`
- Used for: Session token signing

### Optional

**`GOOGLE_SHEETS_API_KEY`**
- Get from: Google Cloud Console
- Used for: Feedback logging to Google Sheets

**`GOOGLE_SHEETS_ID`**
- Get from: Google Sheet URL
- Used with: `GOOGLE_SHEETS_API_KEY`

---

## Troubleshooting

### Build Fails

**Check logs in "Build" tab for:**
- Missing environment variables
- Database connection error
- Invalid NVIDIA API key

**Solution:**
1. Verify all required variables are set
2. Test database connection
3. Check NVIDIA API key validity

### Application Crashes

**Check logs in "Logs" tab:**
- Look for error messages
- Restart the Space if needed

### Slow Responses

**Possible causes:**
- Database too slow
- NVIDIA API busy
- Rate limiting triggered

**Solution:**
- Upgrade Space compute resources
- Check database performance
- Increase rate limit if needed

---

## What's Next?

After backend is deployed:

1. **Build the Frontend** (React + Tailwind)
   - Dark glassmorphism UI
   - Ask | Imagine mode switcher
   - Advanced prompt input box
   - Reasoning panel
   - Rich response formatting

2. **Connect Frontend to Backend**
   - Update API endpoint URLs
   - Configure tRPC client

3. **Test All Features**
   - Ask mode (text generation)
   - Imagine mode (image generation)
   - Search online
   - Think longer (reasoning)

4. **Deploy Frontend**
   - Same Hugging Face Space or separate URL
   - Configure custom domain

---

## Support

- **Deployment issues**: See `DEPLOYMENT.md`
- **Backend details**: See `BACKEND_README.md`
- **Quick setup**: See `QUICKSTART.md`
- **Architecture**: See `ARCHITECTURE.md`

---

## Key Features Deployed

✅ NVIDIA API integration (Llama-3 70B + fallbacks)
✅ DeepSeek-style reasoning
✅ Rate limiting (30 req/min per user)
✅ DuckDuckGo search integration
✅ Database with conversation history
✅ Google Sheets feedback logging
✅ Industrial-standard middleware
✅ Production-ready Docker image
✅ Complete documentation
✅ Health check endpoints

---

## Ready to Deploy? 🚀

1. Download the code
2. Create Hugging Face Space
3. Push code to Space
4. Set environment variables
5. Wait for build
6. Test the health endpoint
7. You're live!

Good luck! 🎉