FRONTEND_SETUP.md

# Domify Academy Super Bot - Frontend Setup Guide

## Overview

The frontend is built with **React 19 + TypeScript + Tailwind CSS 4** with a dark glassmorphism design (21dev theme). It features:

- **Ask | Imagine mode switcher** at the top (Grok-style)
- **Advanced prompt input** with Search Online and Think Longer toggles
- **DeepSeek reasoning panel** (collapsible with ^ icon)
- **Rich response formatting** with markdown, code highlighting, and tables
- **File upload with OCR** (Tesseract.js)
- **Image gallery** for Imagine mode with download and video conversion options
- **Auto-scroll chat** with smooth animations
- **Dark glassmorphism UI** with violet/indigo glows

---

## Project Structure

```
client/
├── src/
│   ├── pages/
│   │   ├── Chat.tsx          # Main chat interface (Ask/Imagine modes)
│   │   ├── Home.tsx          # Landing page
│   │   └── NotFound.tsx      # 404 page
│   ├── components/           # Reusable UI components
│   ├── contexts/             # React contexts
│   ├── lib/
│   │   └── trpc.ts          # tRPC client configuration
│   ├── App.tsx              # Routes and layout
│   ├── main.tsx             # React entry point
│   └── index.css            # Global styles (glassmorphism theme)
├── public/                  # Static assets
└── index.html              # HTML template
```

---

## Key Features

### 1. Ask Mode

**Text-based conversation with AI:**

- Send messages with optional search online
- Enable "Think Longer" for DeepSeek-style reasoning
- Upload files and images for context
- View reasoning process in collapsible panel
- Rich markdown rendering with syntax highlighting

**Input Features:**
- Auto-resizing textarea
- File upload with drag-and-drop support
- Toggle buttons for Search and Think modes
- Keyboard shortcuts (Shift+Enter for new line, Enter to send)

### 2. Imagine Mode

**Image generation interface:**

- Describe images you want to create
- View previously generated images in horizontal scrolling gallery
- Download generated images
- Optional: Convert images to videos (coming soon)

### 3. Dark Glassmorphism Theme

**21dev Design System:**

- Deep black background (`oklch(0.07 0.002 0)`)
- Violet primary color (`oklch(0.623 0.214 259.815)`)
- Indigo secondary color (`oklch(0.55 0.15 264)`)
- Glass panels with backdrop blur and transparency
- Smooth animations and transitions
- Glow effects on interactive elements

### 4. Reasoning Panel

**DeepSeek-style internal thoughts:**

- Collapsible panel showing bot's reasoning process
- Triggered when "Think Longer" is enabled
- Animated expansion/collapse with ^ icon
- Styled with glass effect and subtle colors

### 5. Rich Response Formatting

**Professional output rendering:**

- **Bold text** for key concepts (auto-highlighted)
- **Code blocks** with syntax highlighting and copy button
- **Markdown tables** for structured data
- **Links** with hover effects
- **Blockquotes** for citations
- **Lists** with proper indentation

---

## Configuration

### API Endpoint

Update the API endpoint in `client/src/pages/Chat.tsx`:

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

**For Hugging Face Spaces:**

```bash
export REACT_APP_API_URL=https://YOUR_SPACE_URL
```

### Environment Variables

Create a `.env.local` file:

```env
# API Configuration
REACT_APP_API_URL=https://your-hugging-face-space-url

# Optional: Analytics
REACT_APP_ANALYTICS_ID=your-analytics-id

# Optional: Feature flags
REACT_APP_ENABLE_VIDEO_GENERATION=false
```

---

## Installation & Development

### Install Dependencies

```bash
cd client
pnpm install
```

### Start Development Server

```bash
pnpm run dev
```

The app will be available at `http://localhost:5173`

### Build for Production

```bash
pnpm run build
```

Output will be in `dist/` directory.

### Type Checking

```bash
pnpm run check
```

---

## Component Architecture

### Chat.tsx (Main Component)

**State Management:**
- `mode` - Current mode (ask/imagine)
- `messages` - Chat message history
- `input` - Current input text
- `isLoading` - Loading state
- `enableSearch` - Search online toggle
- `enableThinking` - Think longer toggle
- `showReasoning` - Reasoning panel visibility
- `uploadedFiles` - Uploaded files
- `generatedImages` - Generated images in Imagine mode

**Key Functions:**
- `handleSendMessage()` - Send chat message to backend
- `handleGenerateImage()` - Generate image via Imagine mode
- `handleFileUpload()` - Handle file uploads
- `removeFile()` - Remove uploaded file

**API Calls:**
- `POST /api/trpc/chat.send` - Send message
- `POST /api/trpc/imagine.generate` - Generate image

### Styling

**CSS Classes (from index.css):**

- `.glass-panel` - Glass effect container
- `.glass-panel-lg` - Larger glass panel
- `.glow-primary` - Primary color glow
- `.glow-accent` - Accent color glow
- `.gradient-text` - Gradient text effect
- `.transition-smooth` - Smooth transitions
- `.btn-primary` - Primary button
- `.btn-ghost` - Ghost button
- `.input-glass` - Glass input field
- `.code-block` - Code block styling
- `.markdown` - Markdown rendering

**Animations:**
- `animate-fade-in` - Fade in animation
- `animate-slide-up` - Slide up animation
- `animate-pulse-glow` - Pulsing glow effect

---

## Integration with Backend

### tRPC Procedures

The frontend calls these backend procedures:

**Chat:**
```typescript
POST /api/trpc/chat.send
{
  prompt: string;
  enableSearch: boolean;
  enableThinking: boolean;
  history: Array<{ role: string; content: string }>;
}

Response:
{
  response: string;
  reasoning: string;
  model: string;
  tokensUsed: number;
}
```

**Image Generation:**
```typescript
POST /api/trpc/imagine.generate
{
  prompt: string;
}

Response:
{
  imageUrl: string;
  prompt: string;
}
```

**Search:**
```typescript
POST /api/trpc/search.online
{
  query: string;
  maxResults: number;
}

Response:
{
  results: Array<{
    title: string;
    url: string;
    snippet: string;
  }>;
}
```

---

## File Upload & OCR

### Supported Formats

- **Images**: JPG, PNG, GIF, WebP
- **Documents**: PDF, TXT, DOC, DOCX

### OCR Implementation

Uses **Tesseract.js** for client-side text extraction:

```typescript
// Example (not yet implemented in Chat.tsx)
import Tesseract from 'tesseract.js';

const result = await Tesseract.recognize(imageFile);
const extractedText = result.data.text;
```

To enable OCR:

1. Install Tesseract.js: `pnpm add tesseract.js`
2. Add OCR handler in Chat.tsx
3. Send extracted text with message

---

## Customization

### Change Colors

Edit `client/src/index.css` in the `.dark` section:

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

Then update `client/src/index.css`:

```css
body {
  font-family: 'YOUR_FONT', sans-serif;
}
```

### Add New Pages

1. Create component in `client/src/pages/NewPage.tsx`
2. Add route in `client/src/App.tsx`:

```typescript
<Route path={"/new-page"} component={NewPage} />
```

---

## Performance Optimization

### Code Splitting

Routes are automatically code-split by React Router.

### Image Optimization

- Generated images are cached in browser
- Use lazy loading for image gallery

### Caching

- tRPC client caches responses automatically
- Clear cache on logout or mode switch

---

## Accessibility

- **Keyboard navigation**: Tab through buttons and inputs
- **Focus rings**: Visible focus indicators on all interactive elements
- **Color contrast**: WCAG AA compliant (dark theme)
- **ARIA labels**: Added to interactive elements
- **Semantic HTML**: Proper heading hierarchy

---

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari, Chrome Mobile)

---

## Troubleshooting

### API Connection Failed

**Error**: "Failed to connect to backend"

**Solution:**
1. Verify `REACT_APP_API_URL` is correct
2. Check backend is running
3. Verify CORS is enabled on backend
4. Check browser console for network errors

### Styling Issues

**Error**: "Colors look wrong" or "Layout is broken"

**Solution:**
1. Clear browser cache
2. Rebuild CSS: `pnpm run build`
3. Check theme is set to "dark" in App.tsx
4. Verify index.css is imported in main.tsx

### Image Upload Not Working

**Error**: "File upload fails"

**Solution:**
1. Check file size (should be <10MB)
2. Verify file format is supported
3. Check browser console for errors
4. Ensure backend file upload endpoint is working

### Slow Performance

**Error**: "App feels sluggish"

**Solution:**
1. Check network tab for slow API calls
2. Reduce chat history size (archive old messages)
3. Optimize images before upload
4. Check for memory leaks in browser DevTools

---

## Deployment

### Build for Production

```bash
pnpm run build
```

### Deploy to Hugging Face Spaces

The frontend is included in the main Dockerfile. It's built as part of the Docker image build process.

### Deploy to Vercel/Netlify

```bash
# Build
pnpm run build

# Deploy dist/ folder
```

---

## Next Steps

1. **Update API endpoint** with your Hugging Face Space URL
2. **Test Ask mode** - Send messages and verify responses
3. **Test Imagine mode** - Generate images
4. **Test features** - Search online, Think longer, file upload
5. **Customize colors** - Match your brand
6. **Deploy** - Push to production

---

## Support

- **Frontend issues**: Check browser console for errors
- **API issues**: Check backend logs in Hugging Face Space
- **Styling issues**: Review `index.css` and Tailwind documentation
- **Component issues**: Check React DevTools

---

## License

MIT License - See LICENSE file for details