- Allow and improve viewing of different content types. First type implemented: changelog
This commit is contained in:
Josako
296
documentation/Eveai Chat Client Developer Documentation.md
Normal file
296
documentation/Eveai Chat Client Developer Documentation.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user