backend/docs/README.md

Documentation Index

🚨 Troubleshooting (Start Here)

Quick Fixes

• Embedding Troubleshooting - Fix dimension mismatch errors in 5 minutes
• Logging Guide - Understanding error messages and logs

Common Error Messages

Error	Quick Fix
shapes (768,) and (384,) not aligned	Embedding dimension mismatch
MongoDB connection failed	Check MONGODB_URI in .env
ChromaDB not available	pip install langchain_chroma
OpenAI API key invalid	Update OPENAI_API_KEY in .env

📖 Comprehensive Guides

Setup & Configuration

• Embedding Compatibility Guide - Complete guide to embedding models and dimensions
• Model Configuration Guide - Provider-specific settings, temperature limitations, and best practices
• Architecture Documentation - System overview and design patterns
• Deployment Guide - Production deployment instructions

API & Development

• API Documentation - Detailed API reference
• ChromaDB Refresh Guide - Database management and refresh procedures

🔧 Developer Resources

Configuration Examples

# Most reliable setup (384D embeddings)
EMBEDDING_PROVIDER=huggingface
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# Local inference setup (768D embeddings)  
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5

# Premium quality setup (1536D embeddings)
EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Quick Commands

# Check current embedding configuration
grep EMBEDDING .env

# Test API health
curl http://localhost:8080/health

# Clear conversation memory
curl -X POST http://localhost:8080/clear-memory

# View recent logs
tail -f ./logs/recipe_bot.log

📋 File Organization

docs/
├── README.md                          # This file
├── embedding-troubleshooting.md       # 🚨 Quick fixes
├── embedding-compatibility-guide.md   # 📖 Complete embedding guide
├── model-configuration-guide.md       # ⚙️  LLM provider configurations
├── logging_guide.md                   # 🔍 Log analysis
├── chromadb_refresh.md                # 🔄 Database management
├── api-documentation.md               # 📡 API reference
├── architecture.md                    # 🏗️ System design
└── deployment.md                      # 🚀 Production setup

🆘 Getting Help

1. Check error logs: tail -f ./logs/recipe_bot.log
2. Common issues: Start with Embedding Troubleshooting
3. API problems: See API Documentation
4. Setup issues: Review Embedding Compatibility Guide

---

💡 Tip: Bookmark the Embedding Troubleshooting page - it solves 80% of common issues!