BACKEND_README.md

# Domify Academy Super Bot - Backend Documentation

## Overview

The backend is built with **Node.js + Express + tRPC** and integrates with **NVIDIA APIs** for LLM and image generation. It provides a robust, scalable foundation for the Grok-inspired AI chatbot.

---

## Architecture

```
┌─────────────────────────────────────────┐
│         Frontend (React)                │
│  (Ask | Imagine mode switcher)          │
└──────────────┬──────────────────────────┘
               │ tRPC API calls
               ▼
┌─────────────────────────────────────────┐
│      Backend (Node.js + Express)        │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  tRPC Routers                   │   │
│  │  ├─ chat.send                   │   │
│  │  ├─ imagine.generate            │   │
│  │  └─ search.online               │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  LLM Engine                     │   │
│  │  ├─ Llama-3 70B (primary)       │   │
│  │  ├─ Fallback models             │   │
│  │  └─ Reasoning generation        │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  Image Generation               │   │
│  │  ├─ SDXL                        │   │
│  │  ├─ Flux                        │   │
│  │  └─ Video conversion            │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  Middleware                     │   │
│  │  ├─ Rate limiting               │   │
│  │  ├─ Request logging             │   │
│  │  ├─ Caching                     │   │
│  │  └─ Error handling              │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
  MySQL    NVIDIA API  DuckDuckGo
  (DB)     (LLM/IMG)    (Search)
```

---

## Key Features

### 1. LLM Integration with Smart Fallback

**Primary Model**: Llama-3 70B
**Fallback Chain**: Llama-2 70B → Mistral Large → Llama-3 8B

```typescript
// Automatic fallback if primary model is busy
const response = await generateResponseWithReasoning(
  userPrompt,
  searchResults,
  enableThinking
);
```

### 2. DeepSeek-Style Reasoning

Generate internal thought process before final answer:

```typescript
// With reasoning enabled
const { reasoning, response } = await generateResponseWithReasoning(
  "What is quantum computing?",
  undefined,
  true  // enableThinking
);
```

### 3. Rate Limiting

Token bucket algorithm prevents API abuse:

- **30 requests/minute** per user
- **5 burst requests** allowed
- **Automatic cleanup** of old buckets

```typescript
const { allowed, remainingTokens } = checkRateLimit(userId, "chat");
if (!allowed) {
  // Rate limit exceeded
}
```

### 4. Search Integration

DuckDuckGo search for "Search Online" mode:

```typescript
const results = await searchOnline("latest AI news", 5);
const formatted = formatSearchResults(results);
```

### 5. Database Management

Conversation history, messages, images, and feedback stored in MySQL:

```typescript
// Save a message
await saveMessage(conversationId, "assistant", content, reasoning);

// Get conversation history
const messages = await getConversationMessages(conversationId);
```

### 6. Google Sheets Integration

Log feedback for analytics:

```typescript
await logFeedbackToSheets({
  userId,
  rating: "like",
  comment: "Great response!",
  timestamp: new Date().toISOString()
});
```

---

## API Endpoints (tRPC Procedures)

### Chat Procedures

#### `chat.send` (Protected)

Send a message and get a response.

**Input:**
```typescript
{
  prompt: string;           // User message
  enableSearch: boolean;    // Enable web search
  enableThinking: boolean;  // Enable reasoning
  history: Array<{          // Conversation history
    role: "user" | "assistant";
    content: string;
  }>;
}
```

**Output:**
```typescript
{
  success: boolean;
  response: string;         // LLM response
  reasoning: string;        // Internal thoughts
  model: string;            // Model used
  tokensUsed: number;       // Token count
}
```

### Image Generation Procedures

#### `imagine.generate` (Protected)

Generate an image from a prompt.

**Input:**
```typescript
{
  prompt: string;  // Image description
}
```

**Output:**
```typescript
{
  success: boolean;
  imageUrl: string;  // Generated image URL
  prompt: string;
}
```

### Search Procedures

#### `search.online` (Public)

Search the web using DuckDuckGo.

**Input:**
```typescript
{
  query: string;           // Search query
  maxResults: number;      // Max results (default: 5)
}
```

**Output:**
```typescript
{
  success: boolean;
  results: Array<{
    title: string;
    url: string;
    snippet: string;
  }>;
}
```

---

## Database Schema

### Users Table

```sql
CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  openId VARCHAR(64) UNIQUE NOT NULL,
  email VARCHAR(320),
  name TEXT,
  tier VARCHAR(50) DEFAULT 'free',
  role ENUM('user', 'admin') DEFAULT 'user',
  ipAddress VARCHAR(45),
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### Conversations Table

```sql
CREATE TABLE conversations (
  id INT PRIMARY KEY AUTO_INCREMENT,
  userId INT NOT NULL,
  title TEXT,
  mode ENUM('ask', 'imagine') DEFAULT 'ask',
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### Messages Table

```sql
CREATE TABLE messages (
  id INT PRIMARY KEY AUTO_INCREMENT,
  conversationId INT NOT NULL,
  role ENUM('user', 'assistant') NOT NULL,
  content LONGTEXT NOT NULL,
  reasoning TEXT,
  metadata JSON,
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### Images Table

```sql
CREATE TABLE images (
  id INT PRIMARY KEY AUTO_INCREMENT,
  userId INT NOT NULL,
  conversationId INT,
  prompt TEXT NOT NULL,
  url TEXT NOT NULL,
  metadata JSON,
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### Feedback Table

```sql
CREATE TABLE feedback (
  id INT PRIMARY KEY AUTO_INCREMENT,
  userId INT NOT NULL,
  messageId INT,
  imageId INT,
  rating ENUM('like', 'dislike') NOT NULL,
  comment TEXT,
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## File Structure

```
server/
├── llm.ts                 # LLM engine with NVIDIA integration
├── search.ts              # DuckDuckGo search integration
├── rateLimit.ts           # Rate limiting middleware
├── db.ts                  # Database helper functions
├── googleSheets.ts        # Google Sheets logging
├── middleware.ts          # Industrial-standard middleware
├── routers.ts             # tRPC procedure definitions
└── _core/
    ├── index.ts           # Server entry point
    ├── context.ts         # tRPC context
    ├── trpc.ts            # tRPC setup
    ├── llm.ts             # Built-in LLM helper
    ├── imageGeneration.ts # Built-in image generation
    └── env.ts             # Environment variables
```

---

## Environment Variables

### Required

| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | MySQL connection string |
| `NVIDIA_API_KEY` | NVIDIA API key |
| `JWT_SECRET` | Session token secret |

### Optional

| Variable | Description | Default |
|----------|-------------|---------|
| `GOOGLE_SHEETS_API_KEY` | Google Sheets API key | (disabled) |
| `GOOGLE_SHEETS_ID` | Google Sheet ID | (disabled) |
| `RATE_LIMIT_REQUESTS` | Requests per minute | 30 |
| `RATE_LIMIT_WINDOW` | Rate limit window (seconds) | 3600 |

---

## Industrial-Standard Features

### 1. Caching

In-memory cache for frequently accessed data:

```typescript
cacheManager.set("key", data, 300); // 5 minute TTL
const cached = cacheManager.get("key");
```

### 2. Performance Monitoring

Track operation durations:

```typescript
performanceMonitor.record("llm_call", 1234); // ms
const stats = performanceMonitor.getStats("llm_call");
```

### 3. Request Logging

Automatic request/response logging with performance metrics.

### 4. Error Handling

Comprehensive error handling with proper HTTP status codes.

### 5. Health Checks

Endpoint for monitoring application health:

```
GET /api/health
```

Response:
```json
{
  "status": "healthy",
  "uptime": 3600,
  "database": "connected",
  "cache": "active",
  "memoryUsage": 256
}
```

### 6. Security Headers

Automatic security headers on all responses:

- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Strict-Transport-Security: max-age=31536000`

---

## Development

### Local Setup

```bash
# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your values

# Run database migrations
pnpm run db:push

# Start development server
pnpm run dev
```

### Testing

```bash
# Run tests
pnpm run test

# Watch mode
pnpm run test:watch
```

### Type Checking

```bash
# Check TypeScript
pnpm run check
```

---

## Deployment

See `DEPLOYMENT.md` for complete deployment instructions.

### Quick Deploy to Hugging Face

```bash
# 1. Create a new Space on Hugging Face
# 2. Push code to the Space repository
git push origin main

# 3. Set environment variables in Space settings
# 4. Hugging Face automatically builds and deploys
```

---

## Monitoring

### Logs

Check application logs in Hugging Face Space:

```
Logs tab → Filter by date/time → Search for errors
```

### Metrics

Monitor key metrics:

- **Response time**: Average LLM response time
- **Error rate**: Percentage of failed requests
- **Cache hit rate**: Percentage of cached responses
- **Database performance**: Query execution time

### Alerts

Set up alerts for:

- High error rate (>5%)
- Slow responses (>5s)
- Database connection failures
- Memory usage >80%

---

## Troubleshooting

### Issue: "Rate limit exceeded"

**Cause**: User has exceeded request limit

**Solution**:
1. Wait for rate limit window to reset
2. Upgrade user tier for higher limits
3. Adjust `RATE_LIMIT_REQUESTS` if needed

### Issue: "NVIDIA API error"

**Cause**: Invalid API key or quota exceeded

**Solution**:
1. Verify `NVIDIA_API_KEY` is correct
2. Check NVIDIA API dashboard for quota
3. Wait for quota reset or upgrade plan

### Issue: "Database connection failed"

**Cause**: Invalid connection string or network issue

**Solution**:
1. Verify `DATABASE_URL` format
2. Check database is running and accessible
3. Verify firewall rules allow connection

### Issue: "Out of memory"

**Cause**: Memory leak or insufficient resources

**Solution**:
1. Restart the application
2. Review recent code changes
3. Upgrade Space compute resources

---

## Best Practices

1. **Always use rate limiting** to prevent abuse
2. **Cache frequently accessed data** to improve performance
3. **Log all errors** for debugging and monitoring
4. **Use environment variables** for configuration
5. **Validate user input** before processing
6. **Handle errors gracefully** with proper HTTP status codes
7. **Monitor performance** and optimize bottlenecks
8. **Keep dependencies updated** for security

---

## Support

For issues or questions:

1. Check logs in Hugging Face Space
2. Review `DEPLOYMENT.md` for deployment issues
3. Check `ARCHITECTURE.md` for design details
4. Contact NVIDIA support for API issues

---

## License

MIT License - See LICENSE file for details