eveAI/documentation/Eveai Chat Client Developer Documentation.md

Evie Chat Client - Developer Documentation

Overview

The Evie Chat Client is a modern, customizable chat interface for interacting with eveai specialists. It supports both anonymous and authenticated modes, with initial focus on anonymous mode. The client provides real-time interaction with AI specialists, customizable tenant branding, and European-compliant analytics tracking.

Key Features

• Anonymous Mode: Public access with tenant UUID and API key authentication
• Real-time Communication: Server-Sent Events (SSE) for live updates and intermediate states
• Tenant Customization: Simple CSS variable-based theming with visual editor
• Multiple Choice Options: Dynamic button/dropdown responses from specialists
• Chat History: Persistent ChatSession and Interaction storage
• File Upload Support: Planned for future implementation
• European Analytics: Umami integration for GDPR-compliant tracking

Architecture

Component Structure

eveai_chat_client/
├── app.py                          # Flask app entry point
├── routes/
│   ├── __init__.py
│   ├── chat_routes.py              # Main chat interface routes
│   └── api_routes.py               # SSE/API endpoints
├── services/
│   ├── chat_service.py             # Chat session management
│   ├── specialist_service.py       # Specialist interaction wrapper
│   └── tenant_service.py           # Tenant config & theming
├── templates/
│   ├── base.html                   # Base template
│   ├── chat.html                   # Main chat interface
│   └── components/
│       ├── message.html            # Individual message component
│       ├── options.html            # Multiple choice options
│       └── thinking.html           # Intermediate states display
└── utils/
    ├── auth.py                     # API key validation
    └── tracking.py                 # Umami analytics integration

Integration Approach

• Services Layer: Direct integration with existing eveai services (not API) for better performance
• Database: Utilizes existing ChatSession and Interaction models
• Caching: Leverages existing Redis setup
• Static Files: Uses existing nginx/static structure

URL Structure & Parameters

Main Chat Interface

GET /chat/{tenant_code}/{specialist_id}

Query Parameters:

• api_key (required): Tenant API key for authentication
• utm_source, utm_campaign, utm_medium (optional): Analytics tracking
• Other tracking parameters as needed

Example:

/chat/550e8400-e29b-41d4-a716-446655440000/document-analyzer?api_key=xxx&utm_source=email

API Endpoints

POST /api/chat/{tenant_code}/interact     # Send message to specialist
GET  /api/chat/{tenant_code}/status/{session_id}  # SSE endpoint for updates
GET  /api/tenant/{tenant_code}/theme.css  # Dynamic tenant CSS (if needed)

Authentication & Security

Anonymous Mode

• Tenant Identification: UUID-based tenant codes (not sequential IDs)
• API Key Validation: Required for all anonymous interactions
• Rate Limiting: Implement per-tenant/IP rate limiting
• Input Validation: Sanitize all user inputs and parameters

Security Considerations

• Use tenant UUIDs to prevent enumeration attacks
• Validate API keys against tenant database
• Implement CORS policies for cross-origin requests
• Sanitize all user messages and file uploads

Real-time Communication

Server-Sent Events (SSE)

• Connection: Long-lived SSE connection per chat session
• Message Types:
  • message: Complete specialist response
  • thinking: Intermediate processing states
  • options: Multiple choice response options
  • error: Error messages
  • complete: Interaction completion

SSE Message Format

{
  "type": "thinking",
  "data": {
    "message": "Analyzing your request...",
    "step": 1,
    "total_steps": 3
  }
}

Tenant Customization

Theme Configuration

Stored in tenant table as JSONB column:

ALTER TABLE tenants ADD COLUMN theme_config JSONB;

CSS Variables Approach

Inline CSS variables in chat template:

:root {
  /* Brand Colors */
  --primary-color: {{ tenant.theme_config.primary_color or '#007bff' }};
  --secondary-color: {{ tenant.theme_config.secondary_color or '#6c757d' }};
  --accent-color: {{ tenant.theme_config.accent_color or '#28a745' }};
  
  /* Chat Interface */
  --user-message-bg: {{ tenant.theme_config.user_message_bg or 'var(--primary-color)' }};
  --bot-message-bg: {{ tenant.theme_config.bot_message_bg or '#f8f9fa' }};
  --chat-bg: {{ tenant.theme_config.chat_bg or '#ffffff' }};
  
  /* Typography */
  --font-family: {{ tenant.theme_config.font_family or 'system-ui, -apple-system, sans-serif' }};
  --font-size-base: {{ tenant.theme_config.font_size or '16px' }};
  
  /* Branding */
  --logo-url: url('/api/tenant/{{ tenant.code }}/logo');
  --header-bg: {{ tenant.theme_config.header_bg or 'var(--primary-color)' }};
}

Theme Editor (eveai_app)

Simple form interface with:

• Color pickers for brand colors
• Font selection dropdown
• Logo upload functionality
• Live preview of chat interface
• Reset to defaults option

Multiple Choice Options

Dynamic Rendering Logic

def render_options(options_list):
    if len(options_list) <= 3:
        return render_template('components/options.html', 
                             display_type='buttons', 
                             options=options_list)
    else:
        return render_template('components/options.html', 
                             display_type='dropdown', 
                             options=options_list)

Option Data Structure

{
  "type": "options",
  "data": {
    "question": "How would you like to proceed?",
    "options": [
      {"id": "option1", "text": "Continue analysis", "value": "continue"},
      {"id": "option2", "text": "Generate report", "value": "report"},
      {"id": "option3", "text": "Start over", "value": "restart"}
    ]
  }
}

Analytics Integration

Umami Setup

• European Hosting: Self-hosted Umami instance
• Privacy Compliant: No cookies, GDPR compliant by design
• Tracking Events:
  • Chat session start
  • Message sent
  • Option selected
  • Session duration
  • Specialist interaction completion

Tracking Implementation

// Track chat events
function trackEvent(eventName, eventData) {
  if (window.umami) {
    umami.track(eventName, eventData);
  }
}

File Upload Support (Future)

Planned Implementation

• Multipart Upload: Standard HTML5 file upload
• File Types: Documents, images, spreadsheets
• Storage: Tenant-specific S3 buckets
• Processing: Integration with existing document processing pipeline
• UI: Drag-and-drop interface with progress indicators

Security Considerations

• File type validation
• Size limits per tenant
• Virus scanning integration
• Temporary file cleanup

Development Guidelines

Code Organization

• Follow existing eveai project structure and conventions
• Use existing common/services and common/utils where applicable
• Maintain multi-tenant data isolation
• Implement proper error handling and logging

Testing Strategy

• Unit tests for services and utilities
• Integration tests for chat flow
• UI tests for theme customization
• Load testing for SSE connections
• Cross-browser compatibility testing

Performance Considerations

• Cache tenant configurations in Redis
• Optimize SSE connection management
• Implement connection pooling for database
• Use CDN for static assets
• Monitor real-time connection limits

Deployment

Container Configuration

• New eveai_chat_client container
• Integration with existing docker setup
• Environment configuration for tenant isolation
• Load balancer configuration for SSE connections

Dependencies

• Flask and Flask-restx (existing)
• Celery integration (existing)
• PostgreSQL and Redis (existing)
• Umami analytics client library

Future Enhancements

Authenticated Mode

• User login integration
• Session persistence across devices
• Advanced specialist access controls
• User-specific chat history

Advanced Features

• Voice message support
• Screen sharing capabilities
• Collaborative chat sessions
• Advanced analytics dashboard
• Mobile app integration

Configuration Examples

Environment Variables

CHAT_CLIENT_PORT=5000
TENANT_API_VALIDATION_CACHE_TTL=3600
SSE_CONNECTION_TIMEOUT=300
UMAMI_WEBSITE_ID=your-website-id
UMAMI_SCRIPT_URL=https://your-umami.domain/script.js

Sample Theme Configuration

{
  "primary_color": "#2563eb",
  "secondary_color": "#64748b",
  "accent_color": "#059669",
  "user_message_bg": "#2563eb",
  "bot_message_bg": "#f1f5f9",
  "chat_bg": "#ffffff",
  "font_family": "Inter, system-ui, sans-serif",
  "font_size": "16px",
  "header_bg": "#1e40af"
}

This documentation provides a comprehensive foundation for developing the Evie Chat Client while maintaining consistency with the existing eveai architecture and meeting the specific requirements for anonymous mode interactions with customizable tenant branding.