UneeQ

Frontend Documentation

React + TypeScript Digital Human Interface

Frontend Code
Frontend Component: The interface directory contains a React + TypeScript application providing both kiosk and mobile remote control experiences.
1
Technology Stack

Core Technologies

  • React 18: Component framework
  • TypeScript: Type safety and development experience
  • Vite: Build tool and development server
  • Zustand: State management

Key Integrations

  • UneeQ SDK: Digital human avatars
  • Deepgram SDK: Real-time speech recognition
  • WebSocket: Real-time communication
  • i18next: Multi-language support
2
Architecture Overview

🏗️ Component Architecture

🖥️ Kiosk Interface

Location: src/pages/kiosk/

Primary digital human display with UneeQ integration, voice input, and interactive conversation management.

  • Digital human rendering
  • Voice input processing
  • Session state management
  • Performance monitoring

📱 Remote Interface

Location: src/pages/remote/

Mobile-first interface for remote users to connect and control the kiosk conversation experience.

  • Device pairing via QR codes
  • Real-time message sending
  • Voice message recording
  • Connection status monitoring

⚙️ Shared Services

Location: src/hooks/ & src/contexts/

Common functionality and state management shared across both interfaces.

  • WebSocket communication
  • Configuration management
  • Language switching
  • Performance tracking
3
Key Development Patterns
Auto-Discovery System: The codebase follows "simple, standardized, and extensible" patterns where triggers, events, and listeners are automatically registered via factory patterns.

Factory Pattern Implementation

src/factories/ ├── ActionFactory.ts # WebSocket action creation ├── TriggerFactory.ts # Event trigger registration ├── UneeqEventFactory.ts # UneeQ event handling ├── WebSocketEventFactory.ts # WebSocket event management └── StreamClientFactory.ts # Speech service clients

Hook-Based Architecture

src/hooks/ ├── useWebSocket.ts # Real-time communication ├── useUneeq.ts # Digital human integration ├── useSpeechServices.ts # Voice processing ├── useConfig.tsx # Configuration management └── usePerformanceMonitor.ts # Development metrics
4
Development Commands
Configuration Required: Before running any commands, you must create src/assets/config.yaml from the sample file.

Setup Commands

# Navigate to frontend directory
cd interface/

# REQUIRED: Create configuration file
cp src/assets/config.sample.yaml src/assets/config.yaml
# Edit config.yaml with your environment settings

# Install dependencies
npm install

Development Commands

Core Development

# Start development server
npm run dev              # → http://localhost:5173

# Build for production
npm run build

# Preview production build
npm run preview

Quality & Documentation

# Run linting
npm run lint

# Setup verification
npm run check-setup

# View documentation
npm run docs            # → http://localhost:4000
5
Configuration Guide

The frontend uses a YAML configuration file that controls application behavior, persona settings, and backend connections.

Required Configuration Structure

# src/assets/config.yaml
app:
  name: "Your Kiosk Name"
  environment: "development"  # development/staging/production

personas:
  en:    # Language code
    cloud:
      CDN: "https://cdn-eu.uneeq.io/hosted-experience/deploy/index.js"
      API: "https://api-eu.uneeq.io"
      id: "your-persona-id"
    miniprem:
      CDN: "https://cdn-eu.uneeq.io/hosted-experience/deploy/index.js"
      API: "https://api-eu.uneeq.io"
      id: "your-persona-id"

backend:
  endpoints:
    ws: "ws://localhost:3001"      # WebSocket endpoint
    http: "http://localhost:3000"  # HTTP API endpoint
  key: "your-backend-api-key"
Multi-Language Support: The configuration supports multiple languages (en, fr, de, es, pt, ja, ar) with separate persona configurations for each.
6
Development Features

🔧 Debug Tools

  • Performance Monitor: Real-time metrics overlay
  • Debug Panel: Configuration and state inspection
  • Status Indicators: WebSocket, UneeQ, and service health
  • Console Logging: Detailed development information

🎯 Production Optimizations

  • Build Analysis: Bundle size and performance insights
  • Asset Optimization: Automated image and code optimization
  • Caching Strategy: Optimal cache headers for CDN deployment
  • Performance Monitoring: Production metrics and error tracking
7
Common Issues & Solutions
Issue Symptom Solution
Config Not Found Blank page or config errors Create config.yaml from sample file
WebSocket Disconnected Red "Disconnected" status Start backend service on port 3001
Start Button Disabled Button is grayed out Check WebSocket and UneeQ status indicators
Node Version Error Build/install failures Update to Node.js v20+
Complete Documentation: For detailed implementation guides, architectural decisions, and comprehensive API documentation, visit the frontend README and integrated documentation.

📚 Comprehensive Documentation

Frontend README →

Complete setup instructions, architecture details, and troubleshooting guide.

🌐 Online Documentation

Interactive Documentation →

Browse the complete online documentation with interactive examples.