docs/reference/CLAUDE.md

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

# 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

# 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