UneeQ

Kiosk Application

Digital Human Interactive Experience with Mobile Remote Control

View on GitLab
Welcome! This is the comprehensive documentation for the UneeQ Kiosk Application - a dual-component system featuring digital human interactions with mobile remote control capabilities.

🚀 Project Architecture

🖥️ Frontend Interface

Technology: React + TypeScript + Vite

Purpose: Digital human kiosk interface with AI-powered conversations using UneeQ SDK, plus mobile remote control interface for peer-to-peer messaging.

  • Real-time WebSocket communication
  • Voice input via Deepgram streaming API
  • Multi-language support (7 languages)
  • Zustand-based state management

Explore Frontend Documentation →

☁️ Backend WebSocket API

Technology: AWS Lambda + API Gateway (Serverless)

Purpose: Real-time bidirectional communication and service token management for speech-to-text functionality.

  • WebSocket API for real-time messaging
  • Service token management for Deepgram
  • Peer-to-peer message routing
  • Serverless AWS deployment

Explore Backend Documentation →

🏗️ System Architecture Overview

System Architecture Diagram This diagram shows the complete system architecture and communication flow between all components, using enterprise-standard visual design.
UneeQ Kiosk Application System Architecture Users Kiosk Display Physical Interface Digital Human Avatar Mobile Remote QR Code Connection Voice & Text Control Frontend Layer React + TypeScript Application Kiosk Interface UneeQ Integration Remote Interface P2P Messaging State Management Zustand Stores Session Context WebSocket State Backend Layer WebSocket API AWS Lambda Real-time Messaging Token Management HTTP Service Express API Service Tokens Health Checks External Services UneeQ API Digital Humans Avatar Control Deepgram STT Speech Recognition Voice Processing AWS Lambda Platform Serverless Functions Auto Scaling User Input Remote Control State Updates WebSocket HTTP API Avatar Control Voice Processing Serverless Runtime
1
Key Features & Capabilities

🤖 Digital Human Avatar

AI-powered conversations using UneeQ SDK with multi-language persona support and cloud/miniprem rendering modes.

📱 Mobile Remote Control

Companion mobile interface allowing remote users to connect and control the kiosk conversation experience.

🎤 Real-time Voice Processing

Deepgram streaming API integration for speech-to-text with auto-discovery triggers and event listeners.

⚡ WebSocket Communication

Real-time bidirectional messaging with auto-reconnection and connection management between interfaces.

🎯 Centralized State

Zustand-based shared state management across kiosk and remote interfaces with performance monitoring.

🔄 Auto-Discovery System

Extensible factory patterns for triggers, events, and listeners that automatically register components.

2
Development Requirements
Important: Both frontend and backend components must run together. The frontend requires the backend WebSocket and HTTP services to function properly.

Prerequisites

Required Service Accounts

3
Configuration Requirements
Critical: Both projects require configuration files that don't exist by default. You must create them from sample files before running the applications.

Frontend Configuration

# Required: Create config.yaml
cp interface/src/assets/config.sample.yaml interface/src/assets/config.yaml

Backend Configuration

# Required: Create .env file
cp websocket-api/.env.example websocket-api/.env
# Add your DEEPGRAM_API_KEY and HTTP_SERVICE_API_KEY
4
Quick Start Guide
Ready to get started? Follow our comprehensive setup guide to get both components running locally in development mode.

📚 View Complete Setup Guide →

Frontend Development

cd interface/
npm install
npm run dev  # http://localhost:5173

Backend Development

cd websocket-api/
npm install
npm run dev  # ws://localhost:3001
5
Repository Structure
├── interface/ # Frontend React Application │ ├── src/ │ │ ├── pages/ │ │ │ ├── kiosk/ # Main kiosk interface │ │ │ └── remote/ # Mobile remote control │ │ ├── hooks/ # Custom React hooks │ │ ├── contexts/ # Global state management │ │ └── assets/ │ │ └── config.yaml # Required config (create from sample) │ ├── package.json │ └── README.md # Frontend documentation │ ├── websocket-api/ # Backend Serverless API │ ├── src/ │ │ ├── actions/ # WebSocket action handlers │ │ ├── handlers/ # Lambda function handlers │ │ └── services/ # Business logic services │ ├── .env # Required config (create from sample) │ ├── serverless.yml # AWS deployment config │ ├── package.json │ └── README.md # Backend documentation │ ├── CLAUDE.md # Claude Code guidance └── public/ # This documentation (GitLab Pages)