Skip to content

replit.md

Latest commit

 

History

History
201 lines (163 loc) · 8.35 KB

replit.md

File metadata and controls

201 lines (163 loc) · 8.35 KB

Tavus API Integration - Node.js Express Application

Overview

This is a Node.js Express application that serves as a backend API wrapper for the Tavus API, providing conversation and replica management capabilities. The application is built with a focus on simplicity, reliability, and proper error handling while maintaining a clean separation of concerns through a modular architecture.

System Architecture

The application follows a classic MVC (Model-View-Controller) pattern with additional service and middleware layers:

┌─────────────────┐
│   Express App   │
└─────────────────┘
         │
┌─────────────────┐
│   Middleware    │  ← CORS, Morgan, Validation, Rate Limiting
└─────────────────┘
         │
┌─────────────────┐
│     Routes      │  ← conversations.js, replicas.js
└─────────────────┘
         │
┌─────────────────┐
│  Controllers    │  ← Business logic coordination
└─────────────────┘
         │
┌─────────────────┐
│    Services     │  ← Tavus API integration
└─────────────────┘
         │
┌─────────────────┐
│   Tavus API     │  ← External service
└─────────────────┘

Key Components

Core Application (app.js)

  • Express server setup and configuration
  • Middleware registration (CORS, JSON parsing, logging)
  • Route mounting and health check endpoint
  • Error handling integration

Models Layer (models/)

  • conversationModels.js: Object models and validation for conversation endpoints
  • replicaModels.js: Object models and validation for replica endpoints
  • index.js: Centralized model exports and common utilities
  • Input sanitization and comprehensive validation rules

Services Layer (services/tavusService.js)

  • TavusService: Direct Tavus API integration using axios
  • Handles all HTTP communication with Tavus REST API
  • Provides conversation and replica management methods
  • Implements comprehensive error handling and logging

Controllers (controllers/)

  • ConversationController: Handles conversation-related HTTP requests
  • ReplicaController: Manages replica-related operations
  • ResponseBuilder: Utility class for standardizing API responses
  • Uses object models for consistent request/response formatting
  • Implements centralized validation and error handling
  • Provides standardized pagination and success/error responses

Routes (routes/)

  • conversations.js: RESTful endpoints for conversation management
  • replicas.js: RESTful endpoints for replica operations
  • Implements rate limiting (50 requests/15min for conversations, 30 requests/15min for replicas)
  • Enhanced validation middleware integration with object models

Middleware (middleware/)

  • errorHandler.js: Centralized error handling with proper logging
  • validation.js: Object model-based input validation and sanitization
  • deduplication.js: Request deduplication to prevent duplicate conversation creation
  • Rate limiting implementation using express-rate-limit pattern
  • Query parameter validation for pagination

Utilities (utils/)

  • logger.js: Custom logging utility with configurable log levels
  • Structured JSON logging with timestamps and circular reference protection
  • Environment-based log level configuration

Configuration (config/)

  • environment.js: Centralized environment variable management
  • Validation of required configuration values
  • Default value assignments

Data Flow

  1. Request Flow: Client → Express → Routes → Middleware → Controller → Service → Tavus API
  2. Response Flow: Tavus API → Service → Controller → Routes → Express → Client
  3. Error Flow: Any Layer → Error Handler → Logged Response → Client

API Endpoints

Conversations:

  • POST /api/conversations - Create new conversation
  • GET /api/conversations - List conversations with pagination
  • GET /api/conversations/:id - Get specific conversation
  • PUT /api/conversations/:id - Update conversation
  • PATCH /api/conversations/:id/end - End conversation
  • DELETE /api/conversations/:id - Delete conversation

Replicas:

  • POST /api/replicas - Create new replica
  • GET /api/replicas - List replicas with pagination
  • GET /api/replicas/:id - Get specific replica
  • PUT /api/replicas/:id - Update replica
  • DELETE /api/replicas/:id - Delete replica

Video Room:

  • GET /room?url=MEETING_URL - Video room interface for Tavus conversations

External Dependencies

Primary Dependencies

  • express: Web application framework
  • tavus-js-sdk: Official Tavus API client
  • cors: Cross-origin resource sharing middleware
  • morgan: HTTP request logging
  • dotenv: Environment variable management

Development Philosophy

  • Minimal dependency approach to reduce security surface
  • Use of proven, well-maintained packages
  • No database dependencies (stateless API wrapper)

Deployment Strategy

Environment Configuration

  • Development: NODE_ENV=development, detailed logging
  • Production: NODE_ENV=production, optimized logging
  • Port: Configurable via PORT environment variable (default: 8000)
  • Host: Configurable via HOST environment variable (default: 0.0.0.0)

Required Environment Variables

  • TAVUS_API_KEY: Authentication key for Tavus API
  • NODE_ENV: Application environment (development/production)
  • LOG_LEVEL: Logging verbosity (error/warn/info/debug)

Replit Configuration

  • Configured for Node.js 20 runtime
  • Automatic dependency installation via workflows
  • Port 5000 monitoring for health checks
  • Production-ready server startup command

Recent Changes

  • June 25, 2025: Created comprehensive object models for all API endpoints

    • Added models/conversationModels.js with validation schemas
    • Added models/replicaModels.js with validation schemas
    • Added models/index.js for centralized model exports
    • Updated validation middleware to use object models
    • Added detailed API documentation with examples
    • Fixed error handling to prevent circular reference issues
    • Enhanced input sanitization and parameter validation

  • June 25, 2025: Updated controllers to use object models

    • Added controllers/utils/responseBuilder.js for standardized responses
    • Updated both conversation and replica controllers to use ResponseBuilder
    • Implemented consistent pagination and error response formatting
    • Streamlined query parameter processing and validation
    • Added centralized response utilities for better maintainability

  • June 25, 2025: Fixed error handling and API integration issues

    • Improved Tavus API error handling with specific error messages
    • Added comprehensive API usage examples and documentation
    • Fixed persona_id validation and provided clear error feedback
    • App now handles both valid and invalid requests gracefully

  • June 25, 2025: Added conversation end functionality

    • Added PATCH /api/conversations/:id/end endpoint to end active conversations
    • Updated TavusService with endConversation method
    • Enhanced API documentation with conversation ending examples
    • Provided proper error handling for conversation end operations

  • June 27, 2025: Added video room interface

    • Added GET /room?url=MEETING_URL endpoint for Tavus video conversations
    • Implemented Daily.co integration for video calling interface
    • Created responsive HTML interface with error handling
    • Enhanced server with video room capabilities

  • June 27, 2025: Implemented conversation creation deduplication

    • Added strict rate limiting for conversation creation (5 requests per minute)
    • Created deduplication middleware to prevent duplicate requests
    • Added request tracking and logging for monitoring
    • Implemented 10-second window for duplicate request detection

Changelog

Changelog:
- June 25, 2025. Initial setup with Tavus API integration
- June 25, 2025. Added comprehensive object models and validation

User Preferences

Preferred communication style: Simple, everyday language.