docs/analytics/overview.md

# Analytics Approach for Atlas Chat App

## Overview
This document outlines a simple analytics implementation for the Atlas chat application, designed for learning purposes while maintaining core functionality and insights.

## Database Choice

### Primary Option: MongoDB
- **Rationale**: Document-based storage perfect for analytics data
- **Setup**: MongoDB Atlas free tier (512MB storage, perfect for learning)
- **Driver**: `motor` for async Python operations
- **Benefits**: 
  - Flexible schema for evolving analytics needs
  - Built-in aggregation pipeline for queries
  - JSON-like documents match Python dictionaries

### Alternative Option: JSON Files
- **Use Case**: Ultra-simple setup without external dependencies
- **Storage**: Local JSON files with rotation
- **Benefits**: No database setup required, easy to inspect data
- **Limitations**: Not suitable for production, limited query capabilities

## Data Schema Design

### 1. Chat Sessions
```json
{
  "_id": "session_uuid",
  "start_time": "2024-01-01T10:00:00Z",
  "end_time": "2024-01-01T10:15:00Z",
  "message_count": 8,
  "search_used": true,
  "user_agent": "local_app.py/1.0"
}
```

### 2. Chat Messages
```json
{
  "_id": "message_uuid",
  "session_id": "session_uuid",
  "timestamp": "2024-01-01T10:05:00Z",
  "prompt_length": 45,
  "response_length": 320,
  "used_search": false,
  "response_time_ms": 2500,
  "max_tokens": 500,
  "temperature": 0.7,
  "success": true
}
```

### 3. Search Analytics (Optional)
```json
{
  "_id": "search_uuid",
  "message_id": "message_uuid",
  "timestamp": "2024-01-01T10:05:00Z",
  "search_query": "python machine learning",
  "results_count": 7,
  "search_time_ms": 1200,
  "engines_used": ["brave", "duckduckgo"]
}
```

## Privacy Considerations

### For Learning Project
- Store minimal user data
- No IP address logging
- No personal information storage
- Focus on usage patterns, not user identity

### Data Retention
- Keep data for 30 days maximum
- Automatic cleanup of old records
- Optional: Allow users to opt-out of analytics

## Implementation Architecture

### 1. Analytics Module Structure
```
analytics/
├── __init__.py
├── database.py      # Database connection and operations
├── collectors.py    # Data collection functions
├── models.py        # Data models/schemas
└── dashboard.py     # Analytics endpoints
```

### 2. Integration Points
- **Middleware**: Automatic session and message tracking
- **Decorators**: Performance timing
- **Endpoints**: Manual analytics triggers

### 3. Analytics Endpoints
- `GET /analytics/stats` - Basic usage statistics
- `GET /analytics/dashboard` - Simple HTML dashboard
- `GET /analytics/export` - Data export for analysis

## Key Metrics to Track

### Usage Metrics
- Messages per day/week
- Average session length
- Search usage percentage
- Peak usage hours

### Performance Metrics
- Average response time
- Search performance
- Error rates
- System availability

### Content Metrics
- Popular query types
- Message length distributions
- Search vs. direct query ratios

## Learning Objectives

This implementation teaches:
1. **Database Integration**: Async NoSQL operations
2. **Data Modeling**: Schema design for analytics
3. **Performance Monitoring**: Timing and metrics collection
4. **Web Analytics**: Basic dashboard creation
5. **Privacy**: Responsible data collection practices

## Next Steps
See [implementation-tasks.md](implementation-tasks.md) for the phased implementation plan.