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:**
```bash
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

```bash
pnpm install
```

### Create Environment File

Create `.env` file in project root:

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

```bash
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`:

```typescript
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](https://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

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

```bash
# 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:**
```bash
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`:

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

```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! 🚀**