BackTrack.AI - Chrome Extension

A Chrome extension that provides AI-powered semantic search for your browsing history using FastAPI, Qdrant vector database, and Next.js.

🚀 Features

• Semantic Search: Search your browsing history using natural language queries
• Rich Results: View titles, URLs, snippets, code blocks, and scroll positions
• Modern UI: Clean, responsive interface built with Next.js
• Vector Database: Powered by Qdrant for fast semantic search
• Scroll Position: Remember and restore scroll positions for pages

📋 Prerequisites

• Python 3.8+
• Node.js 16+
• Docker (for Qdrant)
• Chrome browser

🛠️ Setup Instructions

1. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python init_db.py

# Start Qdrant (in a separate terminal)
docker run -d -p 6333:6333 qdrant/qdrant

# Start the backend server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

2. Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Build the Chrome extension
npm run build:extension

3. Load Chrome Extension

1. Open Chrome and go to chrome://extensions/
2. Enable "Developer mode" (toggle in top right)
3. Click "Load unpacked"
4. Select the frontend/out directory

🧪 Testing

Test Backend

cd backend

# Test complete flow
python test_complete_flow.py

# Test individual components
python debug_complete.py
python test_qdrant_setup.py

Test Frontend

1. Open the Chrome extension popup
2. Enter a search query like "React debounce"
3. Verify results are displayed correctly

📁 Project Structure

backtrack-extension/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   ├── models.py       # Database models
│   │   ├── database.py     # Database connection
│   │   └── utils/          # Utilities (Qdrant client)
│   ├── test_*.py          # Test scripts
│   └── requirements.txt    # Python dependencies
├── frontend/               # Next.js frontend
│   ├── src/app/           # React components
│   ├── public/            # Static files
│   └── package.json       # Node.js dependencies
└── README.md              # This file

🔧 API Endpoints

POST /api/generate-embeddings

Generate embeddings for session data and store in PostgreSQL + Qdrant.

Request:

{
  "user_id": "test_user_123",
  "url": "https://example.com",
  "title": "Page Title",
  "text": "Page content...",
  "code_blocks": ["console.log('test');"],
  "timestamp": "2025-01-01T12:00:00",
  "scroll_position": 0.5
}

POST /api/search

Search sessions using semantic search.

Request:

{
  "user_id": "test_user_123",
  "query": "React debounce",
  "top_k": 5
}

Response:

{
  "results": [
    {
      "url": "https://example.com",
      "title": "Page Title",
      "snippet": "Page content snippet...",
      "code_blocks": ["console.log('test');"],
      "timestamp": "2025-01-01T12:00:00",
      "scroll_position": 0.5,
      "score": 0.85
    }
  ]
}

🎯 Usage

1. Start Services: Ensure backend and Qdrant are running
2. Load Extension: Load the Chrome extension in Chrome
3. Search: Click the extension icon and enter natural language queries
4. View Results: Browse through search results with rich metadata
5. Open Pages: Click "Open Page" to navigate to the original page

🔍 Example Queries

• "React debounce"
• "useEffect optimization"
• "JavaScript performance"
• "CSS animations"
• "API authentication"

🛠️ Development

Backend Development

cd backend
# Start with auto-reload
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Development

cd frontend
# Start development server
npm run dev
# Build extension
npm run build:extension

🐛 Troubleshooting

Common Issues

1. Qdrant Connection Failed

   • Ensure Docker is running
   • Check if port 6333 is available
   • Restart Qdrant: docker restart <container_id>

2. Backend Server Not Starting

   • Check if port 8000 is available
   • Verify all dependencies are installed
   • Check virtual environment is activated

3. Extension Not Loading

   • Verify the out directory exists
   • Check manifest.json is in the out directory
   • Ensure all static files are built

4. Search Not Working

   • Verify backend is running on http://localhost:8000
   • Check browser console for CORS errors
   • Ensure sample data is added to the database

Debug Commands

# Test backend components
cd backend
python debug_complete.py

# Test Qdrant directly
python test_qdrant_direct.py

# Test database
python test_database.py

# Test API endpoints
python test_api.py

📝 License

This project is licensed under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📞 Support

For issues and questions:

1. Check the troubleshooting section
2. Review the test scripts
3. Open an issue on GitHub