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

{
  "_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

{
  "_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)

{
  "_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 for the phased implementation plan.