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

---

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

# 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
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

# 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:

# 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
• 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! 🎉