Add analytics documentation and implementation plan

- Add analytics-approach.md: technical approach and database design
- Add analytics-tasks.md: phased implementation roadmap with tasks
- Planning for MongoDB-based session and message analytics
- 4-phase implementation plan for learning project

analytics-approach.md

@@ -0,0 +1,130 @@
+# 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 `analytics-tasks.md` for the phased implementation plan.

analytics-tasks.md

@@ -0,0 +1,182 @@
+# Analytics Implementation Tasks
+
+## Project Overview
+Implement basic analytics and user session tracking for the Atlas chat application in four phases.
+
+---
+
+## Phase 1: Foundation Setup
+**Goal**: Set up database connection and basic infrastructure
+
+### Tasks
+- [ ] **1.1** Add MongoDB dependencies to requirements.txt
+  - Add `motor` (async MongoDB driver)
+  - Add `python-dotenv` (already exists)
+  
+- [ ] **1.2** Set up MongoDB Atlas free account
+  - Create cluster and database
+  - Get connection string
+  - Add to `.env` file
+
+- [ ] **1.3** Create analytics module structure
+  - Create `analytics/` directory
+  - Create `analytics/__init__.py`
+  - Create `analytics/database.py` with connection logic
+
+- [ ] **1.4** Test database connection
+  - Simple connection test function
+  - Add to startup event in app.py
+
+**Deliverables**: Working MongoDB connection, basic module structure
+
+---
+
+## Phase 2: Data Collection
+**Goal**: Implement session tracking and message analytics
+
+### Tasks
+- [ ] **2.1** Create data models
+  - Create `analytics/models.py`
+  - Define Session and Message data classes
+  - Add validation and helper methods
+
+- [ ] **2.2** Implement session management
+  - Create `analytics/collectors.py`
+  - Session creation and tracking functions
+  - Session ID generation and management
+
+- [ ] **2.3** Add message tracking
+  - Message analytics collection function
+  - Performance timing decorators
+  - Integration with chat endpoint
+
+- [ ] **2.4** Update app.py for analytics
+  - Import analytics functions
+  - Add analytics calls to chat endpoint
+  - Add session middleware
+
+**Deliverables**: Automatic data collection on all chat interactions
+
+---
+
+## Phase 3: Analytics Endpoints
+**Goal**: Create endpoints to view collected analytics data
+
+### Tasks
+- [ ] **3.1** Create analytics dashboard module
+  - Create `analytics/dashboard.py`
+  - Basic statistics calculation functions
+  - Data aggregation utilities
+
+- [ ] **3.2** Add basic stats endpoint
+  - `GET /analytics/stats` endpoint
+  - Return JSON with key metrics:
+    - Total messages today/week
+    - Average response time
+    - Search usage percentage
+    - Active sessions
+
+- [ ] **3.3** Add simple HTML dashboard
+  - `GET /analytics/dashboard` endpoint
+  - Basic HTML template with charts
+  - Real-time statistics display
+
+- [ ] **3.4** Add data export endpoint
+  - `GET /analytics/export` endpoint
+  - CSV/JSON export functionality
+  - Date range filtering
+
+**Deliverables**: Functional analytics dashboard and API endpoints
+
+---
+
+## Phase 4: Enhancement & Polish
+**Goal**: Add advanced features and polish the implementation
+
+### Tasks
+- [ ] **4.1** Add search analytics
+  - Track search-specific metrics
+  - Search performance analysis
+  - Popular search terms (anonymized)
+
+- [ ] **4.2** Implement data retention
+  - Automatic cleanup of old data
+  - Configurable retention periods
+  - Database optimization
+
+- [ ] **4.3** Add error tracking
+  - Error analytics collection
+  - Error rate monitoring
+  - System health metrics
+
+- [ ] **4.4** Performance optimization
+  - Database indexing
+  - Async optimization
+  - Memory usage monitoring
+
+- [ ] **4.5** Documentation and testing
+  - Update README with analytics features
+  - Add basic tests for analytics functions
+  - API documentation updates
+
+**Deliverables**: Production-ready analytics system with monitoring
+
+---
+
+## Optional Enhancements
+*These can be added after core implementation*
+
+### Advanced Features
+- [ ] **Real-time WebSocket dashboard**
+- [ ] **Email/Slack alerts for errors**
+- [ ] **Advanced data visualization**
+- [ ] **User behavior analysis**
+- [ ] **A/B testing framework**
+
+### Integration Features  
+- [ ] **Grafana dashboard integration**
+- [ ] **Prometheus metrics export**
+- [ ] **Log aggregation (ELK stack)**
+- [ ] **API rate limiting based on usage**
+
+---
+
+## Success Criteria
+
+### Phase 1 Success
+- ✅ MongoDB connection established
+- ✅ Basic module structure created
+- ✅ Connection test passing
+
+### Phase 2 Success  
+- ✅ All chat messages tracked in database
+- ✅ Session management working
+- ✅ Performance metrics collected
+
+### Phase 3 Success
+- ✅ Analytics dashboard accessible
+- ✅ Key metrics displayed correctly
+- ✅ Data export functionality working
+
+### Phase 4 Success
+- ✅ Search analytics implemented
+- ✅ Data retention policies active
+- ✅ System monitoring in place
+
+---
+
+## Timeline Estimate
+- **Phase 1**: 2-3 hours
+- **Phase 2**: 4-5 hours  
+- **Phase 3**: 3-4 hours
+- **Phase 4**: 3-4 hours
+
+**Total**: ~12-16 hours for complete implementation
+
+---
+
+## Dependencies
+- MongoDB Atlas account (free tier)
+- Python packages: `motor`, `python-dotenv`
+- Basic HTML/CSS knowledge for dashboard
+- Understanding of async Python programming