# 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
```json
{
  "type": "thinking",
  "data": {
    "message": "Analyzing your request...",
    "step": 1,
    "total_steps": 3
  }
}
```

## Tenant Customization

### Theme Configuration
Stored in tenant table as JSONB column:
```sql
ALTER TABLE tenants ADD COLUMN theme_config JSONB;
```

### CSS Variables Approach
Inline CSS variables in chat template:
```css
: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
```python
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
```json
{
  "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
```javascript
// 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
```bash
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
```json
{
  "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.