COMPLETE_SETUP_GUIDE.md

🚀 Domify Academy Super Bot - Complete Setup & Deployment Guide

📦 What You're Getting

A production-ready, full-stack AI chatbot with:

✅ Backend (FastAPI + NVIDIA API)

• Llama-3 70B LLM with smart fallback chain
• SDXL/Flux image generation
• DuckDuckGo search integration
• DeepSeek-style reasoning
• Rate limiting & monitoring
• Google Sheets feedback logging

✅ Frontend (React 19 + TypeScript)

• Dark glassmorphism UI (21dev theme)
• Ask | Imagine mode switcher
• Chat sidebar with local storage
• Advanced prompt input (Search/Think toggles)
• Collapsible reasoning panel
• Rich markdown rendering
• Image gallery with download
• File upload & OCR ready

✅ Deployment

• Dockerfile for Hugging Face Spaces
• Environment configuration
• Complete documentation

---

📥 Step 1: Download & Extract Code

Download the complete code:

wget https://files.manuscdn.com/user_upload_by_module/session_file/310519663512731124/eepQdzwGxcStVZQg.gz -O complete-code.tar.gz
tar -xzf complete-code.tar.gz
cd domify-academy-bot

---

🔧 Step 2: Setup Backend (Local Testing)

Install Dependencies

pnpm install

Create Environment File

Create .env file in project root:

# Database
DATABASE_URL=mysql://user:password@localhost:3306/domify_bot

# NVIDIA API
NVIDIA_API_KEY=your_nvidia_api_key_here

# JWT & OAuth
JWT_SECRET=your_jwt_secret_here
OAUTH_SERVER_URL=https://api.manus.im
VITE_OAUTH_PORTAL_URL=https://manus.im

# App Config
VITE_APP_ID=your_app_id
VITE_APP_TITLE=Domify Academy Bot
VITE_APP_LOGO=https://your-logo-url.png

# Frontend API
REACT_APP_API_URL=http://localhost:3000

Run Backend Locally

pnpm run dev

Server will run on http://localhost:3000

---

🎨 Step 3: Setup Frontend (Local Testing)

Frontend is included in the same project

The frontend automatically starts with the backend. Access it at:

http://localhost:3000/chat

Update API Endpoint (if needed)

Edit client/src/pages/Chat.tsx:

const API_BASE_URL = process.env.REACT_APP_API_URL || "http://localhost:3000";

---

🌐 Step 4: Deploy to Hugging Face Spaces

4.1 Create Hugging Face Space

1. Go to huggingface.co/spaces
2. Click "Create new Space"
3. Select "Docker" SDK
4. Name: domify-academy-bot
5. Choose "Public" (or Private)
6. Click "Create Space"

4.2 Push Code to Hugging Face

# Initialize git (if not already done)
git init
git add .
git commit -m "Initial Domify Academy Bot deployment"

# 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

Note: Replace YOUR_USERNAME with your Hugging Face username.

4.3 Set Environment Variables in Space

1. Go to your Space settings
2. Find "Variables and secrets" section
3. Add these secrets:

Key	Value	Description
DATABASE_URL	mysql://...	Your MySQL connection string
NVIDIA_API_KEY	your_key_here	NVIDIA API key
JWT_SECRET	generate_with_openssl	openssl rand -base64 32
OAUTH_SERVER_URL	https://api.manus.im	OAuth server URL
VITE_OAUTH_PORTAL_URL	https://manus.im	OAuth portal URL
VITE_APP_ID	your_app_id	Application ID
VITE_APP_TITLE	Domify Academy Bot	App title
REACT_APP_API_URL	https://YOUR_SPACE_URL	Your Space URL

4.4 Wait for Build

Hugging Face will automatically:

1. Detect the Dockerfile
2. Build the Docker image
3. Deploy the application

This takes 5-10 minutes. You'll see a "Building" status.

4.5 Access Your Bot

Once deployed, your bot will be available at:

https://YOUR_USERNAME-domify-academy-bot.hf.space

---

📋 File Structure

domify-academy-bot/
├── client/                          # Frontend (React)
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Chat.tsx            # Main chat interface (Ask/Imagine)
│   │   │   ├── Home.tsx            # Landing page
│   │   │   └── NotFound.tsx        # 404 page
│   │   ├── components/
│   │   │   └── ChatSidebar.tsx     # Sidebar with chat history
│   │   ├── App.tsx                 # Routes & layout
│   │   ├── main.tsx                # React entry
│   │   └── index.css               # Global styles (glassmorphism)
│   ├── index.html                  # HTML template
│   └── public/                     # Static assets
├── server/                          # Backend (Express + tRPC)
│   ├── llm.ts                      # NVIDIA LLM integration
│   ├── search.ts                   # DuckDuckGo search
│   ├── rateLimit.ts                # Rate limiting
│   ├── db.ts                       # Database helpers
│   ├── googleSheets.ts             # Google Sheets integration
│   ├── middleware.ts               # Logging, caching, monitoring
│   ├── routers.ts                  # tRPC procedures
│   └── _core/                      # Framework internals
├── drizzle/                         # Database schema & migrations
│   ├── schema.ts                   # Table definitions
│   └── migrations/                 # SQL migrations
├── Dockerfile                       # Docker build config
├── DEPLOYMENT.md                    # Deployment guide
├── BACKEND_README.md                # Backend documentation
├── FRONTEND_SETUP.md                # Frontend documentation
├── QUICKSTART.md                    # 5-minute setup
└── package.json                     # Dependencies

---

🔑 Environment Variables Explained

Backend Variables

Variable	Purpose	Example
DATABASE_URL	MySQL connection	mysql://user:pass@host/db
NVIDIA_API_KEY	NVIDIA API key	nvapi-...
JWT_SECRET	Session signing	base64_random_string
OAUTH_SERVER_URL	OAuth provider	https://api.manus.im

Frontend Variables

Variable	Purpose	Example
REACT_APP_API_URL	Backend API URL	https://your-space.hf.space
VITE_APP_TITLE	App title	Domify Academy Bot
VITE_APP_LOGO	Logo URL	https://...logo.png

---

🧪 Testing Locally

Test Backend API

# Start dev server
pnpm run dev

# In another terminal, test chat endpoint
curl -X POST http://localhost:3000/api/trpc/chat.send \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello, how are you?",
    "enableSearch": false,
    "enableThinking": false,
    "history": []
  }'

Test Frontend

1. Open http://localhost:3000/chat
2. Try Ask mode:
   • Type a message
   • Click Send
   • See response appear
3. Try Imagine mode:
   • Switch to Imagine
   • Type image description
   • Click "Generate Image"
4. Test sidebar:
   • Create multiple chats
   • Switch between them
   • Delete a chat
   • Verify local storage persistence

---

🐛 Troubleshooting

Backend Won't Start

Error: Cannot find module 'express'

Solution:

pnpm install
pnpm run dev

Database Connection Failed

Error: ECONNREFUSED 127.0.0.1:3306

Solution:

1. Ensure MySQL is running
2. Check DATABASE_URL is correct
3. Verify credentials

Frontend Not Loading

Error: 404 Not Found or blank page

Solution:

1. Check dev server is running: pnpm run dev
2. Clear browser cache
3. Check browser console for errors

API Endpoint Not Working

Error: Failed to fetch or CORS error

Solution:

1. Verify REACT_APP_API_URL is correct
2. Check backend is running
3. Ensure CORS is enabled on backend
4. Check network tab in browser DevTools

Hugging Face Build Failed

Error: Docker build error

Solution:

1. Check Dockerfile syntax
2. Verify all environment variables are set
3. Check Space logs for detailed error
4. Try rebuilding the Space

---

📱 Features Walkthrough

Ask Mode

1. Send Message

   • Type question
   • Press Enter or click Send
   • View response with markdown rendering

2. Search Online

   • Click "Search Online" toggle
   • Send message
   • Bot will search web for context

3. Think Longer

   • Click "Think Longer" toggle
   • Send message
   • View reasoning process in collapsible panel

4. Upload Files

   • Click "Upload" button
   • Select image or document
   • Send message with file context

5. Chat History

   • View all chats in sidebar
   • Click to switch between chats
   • Delete chats with trash icon
   • All stored in browser local storage

Imagine Mode

1. Generate Image

   • Type image description
   • Click "Generate Image"
   • Wait for generation

2. View Gallery

   • Generated images appear in gallery
   • Scroll horizontally to see all
   • Click "Download" to save image
   • "Video" button coming soon

---

🎨 Customization

Change Colors

Edit client/src/index.css:

.dark {
  --primary: oklch(0.623 0.214 259.815);      /* Violet */
  --secondary: oklch(0.55 0.15 264);          /* Indigo */
  --accent: oklch(0.65 0.18 280);             /* Light indigo */
  --background: oklch(0.07 0.002 0);          /* Deep black */
  --foreground: oklch(0.95 0.002 0);          /* Near white */
}

Change Fonts

Edit client/index.html:

<link href="https://fonts.googleapis.com/css2?family=YOUR_FONT&display=swap" rel="stylesheet">

Change App Title

Set VITE_APP_TITLE environment variable

---

📊 Database Schema

Tables

1. users - User accounts
2. conversations - Chat sessions
3. messages - Individual messages
4. generated_images - Generated images
5. feedback - User feedback (logged to Google Sheets)

---

🔐 Security Best Practices

1. Never commit .env file - Use environment variables in deployment
2. Keep API keys secret - Use Hugging Face Spaces secrets
3. Enable HTTPS - Hugging Face provides SSL automatically
4. Rate limiting - Enabled by default (30 req/min per user)
5. Input validation - All inputs sanitized on backend

---

📈 Performance Tips

1. Cache search results - 5-minute TTL for DuckDuckGo searches
2. Lazy load images - Images load on demand in gallery
3. Compress responses - Gzip enabled on all API responses
4. Browser caching - Chat history stored locally
5. Monitor usage - Check logs for slow endpoints

---

🚀 Next Steps

1. ✅ Download and extract code
2. ✅ Test locally with pnpm run dev
3. ✅ Create Hugging Face Space
4. ✅ Set environment variables
5. ✅ Push code to Hugging Face
6. ✅ Wait for build completion
7. ✅ Access your bot at Space URL
8. ✅ Start using!

---

📞 Support

Common Issues

• Build fails: Check Dockerfile and environment variables
• API errors: Check backend logs in Space
• Frontend blank: Check browser console for errors
• Slow responses: Check NVIDIA API quota

Documentation

• BACKEND_README.md - Backend API reference
• FRONTEND_SETUP.md - Frontend customization
• DEPLOYMENT.md - Detailed deployment guide
• QUICKSTART.md - 5-minute setup

---

🎉 You're Ready!

Your Domify Academy Super Bot is ready to deploy. Follow the steps above and you'll have a production-ready AI chatbot running on Hugging Face Spaces in minutes!

Questions? Check the documentation files or review the code comments.

Happy coding! 🚀