# Talk2Me Admin Analytics Dashboard

A comprehensive analytics dashboard for monitoring and managing the Talk2Me application.

## Features

### Real-time Monitoring
- **Request Volume**: Track requests per minute, hour, and day
- **Active Sessions**: Monitor current active user sessions
- **Error Rates**: Real-time error tracking and analysis
- **System Health**: Monitor Redis, PostgreSQL, and ML services status

### Analytics & Insights
- **Translation & Transcription Metrics**: Usage statistics by operation type
- **Language Pair Analysis**: Most popular translation combinations
- **Response Time Monitoring**: Track performance across all operations
- **Cache Performance**: Monitor cache hit rates for optimization

### Performance Metrics
- **Response Time Percentiles**: P95 and P99 latency tracking
- **Throughput Analysis**: Requests per minute visualization
- **Slow Request Detection**: Identify and analyze performance bottlenecks
- **Resource Usage**: Memory and GPU utilization tracking

### Data Management
- **Export Capabilities**: Download analytics data in JSON format
- **Historical Data**: View trends over time (daily, weekly, monthly)
- **Error Logs**: Detailed error tracking with stack traces
- **Session Management**: Track and manage user sessions

## Setup

### 1. Database Setup

Initialize the analytics database tables:

```bash
python init_analytics_db.py
```

This creates the following tables:
- `error_logs`: Detailed error tracking
- `request_logs`: Request-level analytics
- `translation_logs`: Translation operation metrics
- `transcription_logs`: Transcription operation metrics
- `tts_logs`: Text-to-speech operation metrics
- `daily_stats`: Aggregated daily statistics

### 2. Configuration

Set the following environment variables:

```bash
# Admin access token (required)
export ADMIN_TOKEN="your-secure-admin-token"

# Database configuration
export DATABASE_URL="postgresql://user:password@localhost/talk2me"

# Redis configuration
export REDIS_URL="redis://localhost:6379/0"
```

### 3. Access the Dashboard

1. Navigate to: `http://your-domain/admin`
2. Enter your admin token
3. Access the analytics dashboard

## Dashboard Sections

### Overview Cards
- Total Requests (all-time and today)
- Active Sessions (real-time)
- Error Rate (24-hour percentage)
- Cache Hit Rate (performance metric)

### Charts & Visualizations

#### Request Volume Chart
- Toggle between minute, hour, and day views
- Real-time updates every 5 seconds
- Historical data for trend analysis

#### Language Pairs Donut Chart
- Top 6 most used language combinations
- Visual breakdown of translation patterns

#### Operations Bar Chart
- Daily translation and transcription counts
- 7-day historical view

#### Response Time Line Chart
- Average, P95, and P99 response times
- Broken down by operation type

#### Error Analysis
- Error type distribution pie chart
- Recent errors list with details
- Timeline of error occurrences

### Performance Table
- Detailed metrics for each operation type
- Average response times
- 95th and 99th percentile latencies

## Real-time Updates

The dashboard uses Server-Sent Events (SSE) for real-time updates:
- Automatic refresh every 5 seconds
- Connection status indicator
- Automatic reconnection on disconnect

## Data Export

Export analytics data for external analysis:

1. Click "Export Data" in the navigation
2. Choose data type:
   - `requests`: Request and operation counts
   - `errors`: Error logs and details
   - `performance`: Response time metrics
   - `all`: Complete data export

## API Endpoints

The admin dashboard provides the following API endpoints:

### Authentication Required
All endpoints require the `X-Admin-Token` header.

### Available Endpoints

#### Overview Stats
```
GET /admin/api/stats/overview
```
Returns overall system statistics

#### Request Statistics
```
GET /admin/api/stats/requests/{timeframe}
```
Timeframes: `minute`, `hour`, `day`

#### Operation Statistics
```
GET /admin/api/stats/operations
```
Translation and transcription metrics

#### Error Statistics
```
GET /admin/api/stats/errors
```
Error types, timeline, and recent errors

#### Performance Statistics
```
GET /admin/api/stats/performance
```
Response times and throughput metrics

#### Data Export
```
GET /admin/api/export/{data_type}
```
Data types: `requests`, `errors`, `performance`, `all`

#### Real-time Updates
```
GET /admin/api/stream/updates
```
Server-Sent Events stream for real-time updates

## Mobile Optimization

The dashboard is fully responsive and optimized for mobile devices:
- Touch-friendly controls
- Responsive charts that adapt to screen size
- Collapsible navigation for small screens
- Optimized data tables for mobile viewing

## Security

- Admin token authentication required
- Session-based authentication after login
- Separate CORS configuration for admin endpoints
- All sensitive data masked in exports

## Troubleshooting

### Dashboard Not Loading
1. Check Redis and PostgreSQL connections
2. Verify admin token is set correctly
3. Check browser console for JavaScript errors

### Missing Data
1. Ensure analytics middleware is initialized
2. Check database tables are created
3. Verify Redis is running and accessible

### Real-time Updates Not Working
1. Check SSE support in your reverse proxy
2. Ensure `X-Accel-Buffering: no` header is set
3. Verify firewall allows SSE connections

## Performance Considerations

- Charts limited to reasonable data points for performance
- Automatic data aggregation for historical views
- Efficient database queries with proper indexing
- Client-side caching for static data

## Future Enhancements

- WebSocket support for lower latency updates
- Customizable dashboards and widgets
- Alert configuration for thresholds
- Integration with external monitoring tools
- Machine learning for anomaly detection