Backend Documentation - UneeQ Kiosk Application

Backend Component: The websocket-api directory contains a serverless AWS Lambda application providing WebSocket communication and service token management.

Serverless Architecture

AWS Services

AWS Lambda: Serverless compute functions
API Gateway: WebSocket and HTTP API management
CloudFront: CDN distribution
CloudFormation: Infrastructure as code

Core Technologies

Node.js 20: Runtime environment
TypeScript: Type safety and development experience
Serverless Framework: Deployment and management
Deepgram SDK: Speech-to-text service integration

API Capabilities

🔄 WebSocket Message Flow

Interactive Message Flow This sequence diagram shows the complete WebSocket communication flow between kiosk, backend API, and remote interfaces, including service token management and peer-to-peer messaging.

sequenceDiagram participant K as Kiosk Interface participant WS as WebSocket API participant R as Remote Interface participant DG as Deepgram Service participant UQ as UneeQ Digital Human Note over K,R: Initial Connection Setup K->>WS: Connect WebSocket WS->>K: Connection established R->>WS: Connect WebSocket WS->>R: Connection established Note over K,R: Service Token Acquisition K->>WS: {"action": "serviceToken", "provider": "deepgram", "service": "stt"} WS->>DG: Request temporary token DG->>WS: Return ephemeral token WS->>K: {"type": "serviceToken", "data": {...}} Note over K,R: Peer Connection R->>WS: {"action": "getConnectionId"} WS->>R: {"type": "connectionId", "data": "ABC123"} R->>K: Share connection ID (QR code/manual) K->>WS: {"action": "peerConnect", "peerId": "ABC123"} WS->>R: Notify peer connection established WS->>K: Confirm peer connection Note over K,R: Real-time Communication R->>WS: {"action": "peerMessage", "peerId": "kiosk_id", "payload": {"message": "Hello!"}} WS->>K: Route message to kiosk K->>UQ: Process message with digital human UQ->>K: Generate response K->>WS: {"action": "peerMessage", "peerId": "remote_id", "payload": {"response": "Hi there!"}} WS->>R: Route response to remote

🔌 WebSocket Actions

Connection Management

getConnectionId - Get current connection ID
peerConnect - Establish peer connection
CheckPeerConnection - Verify peer status

Service Integration

serviceToken - Generate Deepgram tokens
Token expiration management
Provider validation

Messaging

peerMessage - Send messages between clients
Real-time message routing
Connection lifecycle handling

🌐 HTTP Endpoints

Service Token Endpoint

GET /service-token?provider=deepgram&service=stt
Headers: x-api-key: YOUR_API_KEY

Response:
{
  "provider": "deepgram",
  "service": "stt",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expiresAtMs": 1672531200000
}

Code Architecture

Action-Based Design: Each WebSocket action has dedicated handler classes with standardized response formatting via response factory patterns.

Project Structure

websocket-api/
├── src/
│   ├── actions/          # WebSocket action handlers
│   │   ├── GetConnectionIdAction.ts
│   │   ├── PeerConnectAction.ts
│   │   ├── ServiceTokenAction.ts
│   │   └── PeerMessageAction.ts
│   ├── handlers/         # Lambda function handlers
│   │   ├── connect.ts    # WebSocket connection handler
│   │   ├── disconnect.ts # WebSocket disconnection handler
│   │   ├── default.ts    # Default message handler
│   │   └── httpServiceToken.ts # HTTP token handler
│   ├── interfaces/       # TypeScript interfaces
│   ├── models/          # Data models and enums
│   ├── responses/       # Response classes
│   ├── services/        # Business logic services
│   │   └── DeepgramService.ts
│   └── utils/           # Utility functions
├── serverless.yml       # AWS deployment configuration
├── .env                 # Environment variables (create from sample)
└── package.json

Handler Pattern

// Example action handler structure
export class ServiceTokenAction implements IAction {
  async execute(event: APIGatewayProxyEvent): Promise<ActionResponse> {
    // Validate request
    // Generate service token
    // Return standardized response
  }
}

Development Commands

Environment Required: You must create a .env file with your Deepgram API key and HTTP service API key before running.

Setup Commands

# Navigate to backend directory
cd websocket-api/

# REQUIRED: Create environment file
cp .env.example .env
# Add DEEPGRAM_API_KEY and HTTP_SERVICE_API_KEY

# Install dependencies
npm install

Development Commands

Local Development

# Start local development server
npm run dev              # WebSocket: ws://localhost:3001
                        # HTTP: http://localhost:3000

# Build for deployment
npm run build

# Run tests
npm run test

Quality Assurance

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# TypeScript type checking
npm run typecheck

AWS Deployment

🚀 Smart Deployment (Recommended)

Automated Retry: The deployment includes smart retry logic with automatic cleanup and exponential backoff for handling deployment failures.

Production Deployment

# Deploy to production with retry logic
npm run deploy:prod

# Deploy to development
npm run deploy:dev

Cleanup Failed Deployments

# Clean up failed deployment
npm run cleanup:prod

# Then retry deployment
npm run deploy:prod

Deployment Features

Automatic Retry: Recoverable failures (S3 bucket conflicts, rate limiting)
Auto-cleanup: Failed deployments are automatically cleaned up
Smart Error Detection: Distinguishes between recoverable and permanent errors
Exponential Backoff: Intelligent retry timing between attempts
Environment Awareness: Respects .env file settings and configuration

Environment Configuration

Required Environment Variables

# .env file configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_here
HTTP_SERVICE_API_KEY=your_secure_api_key_for_http_endpoints

# Optional deployment settings
AWS_REGION=us-east-2
NODE_RUNTIME=nodejs20.x
LOG_LEVEL=info
WEBSOCKET_PORT=3001
HTTP_PORT=3000
CLOUDFRONT_PRICE_CLASS=PriceClass_100

🔑 Getting Deepgram API Key

Sign up at Deepgram Console
Create a new project
Generate API key from project settings
Copy the key to your .env file

🔒 HTTP Service API Key

Generate a secure token to protect HTTP endpoints:

# Generate secure 32-character base64 key
openssl rand -base64 32

Example format: sk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p

CORS & Security

Developer-Friendly CORS: Common development origins are pre-configured, including localhost ports 3000, 5173, and 8080, plus Vercel and Netlify deployments.

Pre-configured Origins (No Setup Required)

http://localhost:3000 - React, Next.js default
http://localhost:5173 - Vite default
http://localhost:8080 - Vue CLI default
https://*.vercel.app - Vercel deployments
https://*.netlify.app - Netlify deployments

Production CORS Setup

# Add to .env for production domains
CORS_ORIGIN=https://your-app.com

# Multiple domains (comma-separated)
CORS_ORIGIN=https://your-app.com,https://staging.your-app.com

Testing & Verification

Manual Testing

Test HTTP Service Token Endpoint

curl -H "x-api-key: YOUR_API_KEY" \
  "https://your-api-domain/prod/service-token?provider=deepgram&service=stt"

# Expected Response:
{
  "provider": "deepgram",
  "service": "stt",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expiresAtMs": 1672531200000
}

Test WebSocket Connection

# Install wscat globally
npm install -g wscat

# Connect to WebSocket
wscat -c "wss://your-ws-domain/prod"

# Send service token request
{"action":"serviceToken","provider":"deepgram","service":"stt"}

Common Issues & Solutions

Issue	Symptom	Solution
Missing Deepgram Key	"Missing required environment variable"	Add valid DEEPGRAM_API_KEY to .env file
Connection Gone (410)	"Connection is gone" error	Normal behavior when WebSocket closes
Deployment Fails	Permissions or S3 bucket errors	Use cleanup script then retry deployment
Unsupported Provider	"Unsupported provider/service" error	Only supports provider:"deepgram", service:"stt"

Complete Documentation: For detailed AWS deployment instructions, API examples, and comprehensive troubleshooting, visit the backend README.

📚 Comprehensive Documentation

Backend README →

Complete AWS setup, deployment instructions, and API reference.

🌐 Online Documentation

Interactive Documentation →

Browse the complete online documentation with examples.