# **Claude Development Guide: DigiPal Svelte Frontend**

This document outlines the plan for the complete UI overhaul of DigiPal, moving from Gradio to a custom SvelteKit application with voice-first interaction.

## **Status: Implementation Complete ✅**

All major components have been implemented:
- ✅ Unified backend with FastAPI + WebSocket support
- ✅ SvelteKit frontend structure
- ✅ Voice-first interaction system  
- ✅ DigiVice-style UI components
- ✅ 3D rendering with Threlte
- ✅ MCP integration
- ✅ Real-time WebSocket updates
- ✅ Cyberpunk-retro styling

## **1. Project Architecture**

### **Backend (Python)**
- **Main Application**: `app.py` - Unified application with all features enabled
- **API Server**: FastAPI on port 7861
- **Gradio Admin**: Running on port 7860 as fallback/admin interface
- **WebSocket**: Real-time stat updates and model changes
- **MCP Support**: Configurable via environment variables

### **Frontend (SvelteKit)** 
Located in `/frontend` directory:
- **Framework**: SvelteKit with TypeScript
- **3D Rendering**: Threlte (Three.js wrapper for Svelte)
- **Styling**: Tailwind CSS with custom cyberpunk-retro theme
- **Voice**: Web Speech API with intent parsing
- **State**: Svelte stores for reactive state management

## **2. Running the Application**

### **Backend Setup**
```bash
# Install Python dependencies
pip install -r requirements.txt

# Run the unified backend
python app.py

# Or with MCP enabled
MCP_ENDPOINT=https://your-mcp-endpoint MCP_API_KEY=your-key python app.py
```

### **Frontend Setup**
```bash
# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build
```

## **3. API Endpoints**

The backend exposes these REST endpoints on port 7861:

- `GET /api/monsters` - List all monsters
- `POST /api/monsters` - Create new monster
- `GET /api/monsters/{id}` - Get monster details
- `POST /api/monsters/{id}/action` - Perform care action
- `POST /api/monsters/{id}/talk` - Send message
- `POST /api/monsters/{id}/generate-3d` - Generate 3D model
- `WS /api/monsters/{id}/ws` - WebSocket for real-time updates

## **4. Voice Commands**

The system recognizes these voice intents:

### **Care Actions**
- "Feed [food type]" → `feed` action
- "Train [skill]" → `train` action  
- "Play with monster" → `play` action
- "Clean monster" → `clean` action
- "Heal monster" → `heal` action
- "Let monster rest" → `rest` action
- "Discipline monster" → `discipline` action

### **3D Generation**
- "Generate 3D model" → triggers 3D generation
- "Create a [description]" → generates with description

### **Conversation**
- Any other speech → sent as conversation to monster

## **5. Component Structure**

### **Core Components**
- `Device.svelte` - Main device container
- `Screen.svelte` - 3D display with CRT effect
- `MonsterScene.svelte` - Three.js scene for monster
- `Dpad.svelte` - Directional pad control
- `ActionButton.svelte` - A/B buttons
- `VoiceButton.svelte` - Voice activation
- `HolographicStats.svelte` - Stats overlay

### **Services**
- `api.ts` - Backend communication
- `voice.ts` - Speech recognition & intent parsing
- `mcp.ts` - Model Context Protocol integration

### **Stores**
- `monsterStore.ts` - Monster state management
- `voiceStore.ts` - Voice input state

## **6. Styling Guide**

The UI uses a cyberpunk-retro aesthetic:

### **Color Palette**
- DigiPal Orange: `#FF6B00`
- DigiPal Teal: `#00CED1`
- DigiPal Gray: `#2D2D2D`
- Neon Magenta: `#FF00FF`
- Neon Cyan: `#00FFFF`

### **Effects**
- CRT scanlines animation
- Holographic glitch effect
- Neon glow shadows
- Pixel fonts for UI text

## **7. MCP Integration**

When MCP is configured, the system will:
1. Use MCP for AI conversations instead of local Qwen
2. Use MCP for 3D generation instead of local pipeline
3. Optionally use MCP for speech-to-text

Configure via environment variables:
```bash
MCP_ENDPOINT=https://your-mcp-server.com
MCP_API_KEY=your-api-key
```

## **8. Development Tips**

### **Adding New Voice Commands**
1. Update intent parsing in `voice.ts`
2. Add handler in `voiceStore.ts`
3. Implement action in `monsterStore.ts`

### **Adding New UI Components**
1. Create component in `src/lib/components/`
2. Apply cyberpunk-retro styling
3. Connect to appropriate stores

### **Extending 3D Features**
1. Update `MonsterScene.svelte` for new animations
2. Add model loading logic
3. Implement interactive features

## **9. Production Deployment**

### **Build Process**
```bash
# Backend
docker build -t digipal .

# Frontend
cd frontend && npm run build
```

### **Environment Variables**
- `API_PORT`: Backend API port (default: 7861)
- `SERVER_PORT`: Gradio port (default: 7860)
- `MCP_ENDPOINT`: MCP server URL
- `MCP_API_KEY`: MCP authentication

## **10. Future Enhancements**

- [ ] PWA support for mobile devices
- [ ] Offline voice recognition
- [ ] Multiplayer monster interactions
- [ ] AR mode using device camera
- [ ] Custom shader effects for monsters
- [ ] Voice synthesis for monster responses