# Atlas Chat API - Project Context

## Project Overview
Atlas is a FastAPI-based chat application with web search capabilities and analytics tracking. The system uses Google Gemini AI with combined Brave/DuckDuckGo search integration for enhanced responses.

## Current Implementation Status

### Phase 1 & 2 Complete: Analytics Foundation
- ✅ **MongoDB Integration**: Motor async driver for analytics storage
- ✅ **Session Tracking**: UUID-based session management with HTTP headers
- ✅ **Data Models**: Session, Message, SearchAnalytics with Pydantic validation
- ✅ **Database Collections**: Sessions, messages, search_analytics
- ✅ **Performance Monitoring**: PerformanceTimer context manager
- ✅ **Graceful Fallback**: System works with/without MongoDB connection

### Key Components

#### Core Files
- **app.py**: Main FastAPI application with chat endpoint and analytics integration
- **local_app.py**: Interactive terminal client with session persistence
- **requirements.txt**: Dependencies including motor for MongoDB

#### Analytics Module (`analytics/`)
- **`__init__.py`**: Module exports and clean API
- **`database.py`**: MongoDB connection management with fallback
- **`models.py`**: Pydantic data models (Session, Message, SearchAnalytics)
- **`collectors.py`**: Data collection functions and session management

#### Documentation
- **`analytics-approach.md`**: Technical approach and design decisions
- **`analytics-tasks.md`**: Phased implementation roadmap

### Technical Architecture

#### Session Management
```python
# HTTP header-based session tracking
headers["X-Session-ID"] = session_id
```

#### Analytics Data Flow
1. Client sends request with optional session ID header
2. FastAPI creates/retrieves session
3. Performance timer tracks response time
4. Message analytics stored in MongoDB
5. Session ID returned in response headers

#### Search Integration
- **Combined Search**: Brave API + DuckDuckGo with fallback
- **NLP Processing**: spaCy + RAKE for search term extraction
- **Result Deduplication**: URL-based filtering
- **Timeout Handling**: 12s overall, 8s per engine

### Current Issues to Address
- Type checking errors in `app.py` around search result handling
- Deprecated `@app.on_event` usage (should migrate to lifespan handlers)
- Unused imports and variables
- Error handling for analytics import failures

### Environment Requirements
```
GOOGLE_API_KEY=your_gemini_api_key
BRAVE_API_KEY=your_brave_api_key  
MONGODB_URL=mongodb://localhost:27017  # Optional
MONGODB_DATABASE=atlas_analytics       # Optional
```

### Next Phase (Phase 3) - Analytics Endpoints
When requested, implement:
- `/analytics/stats` - Session and message statistics
- `/analytics/sessions/{session_id}` - Detailed session data
- Basic analytics dashboard
- Data export functionality

### Git Branch Structure
- **main**: Core chat functionality
- **with-analytics**: Current branch with analytics implementation

### Usage
```bash
# Start API server
python app.py

# Start interactive client
python local_app.py
```

### Key Design Decisions
1. **NoSQL Choice**: MongoDB for flexible analytics schema
2. **Session Persistence**: HTTP headers for stateless API design
3. **Graceful Degradation**: Analytics failures don't break chat functionality
4. **Performance Focus**: Async operations throughout
5. **Privacy by Design**: No sensitive data in analytics logs