🐝 Reading Bee Project Introduction

Welcome to Reading Bee, where every book finds its buzz! ✨

Reading Bee is an online database and personalized book recommendation platform. It integrates an LLM chatbot, advanced search, and similarity-based recommendations into one unified system.

✨ At a Glance

1. LLM Chatbot for book suggestions
2. Advanced Book Search & Filtering
3. Save favorite books to "My List"
4. Similar Book Recommendations based on semantic search
5. Full-Stack: backend + frontend + PostgreSQL database
6. Data engineering and sentiment analysis

📝 Key Features

1. LLM Chatbot:

• 💬 A conversational interface based on Retrieval-Augmented Generation (RAG). User can ask for book suggestions in natural language. Ollama LLM Chatbot returns relevant titles and summarize results (embeddings and metadata).

• ⚙ LLM dynamically triggers tool calling to backend. User messages (such as book descriptions or ISBNs) are parsed and perform a vector search (PostgreSQL + pgvector/FAISS) to retrieve similar books.

2. Book Search & Filtering

• ⚡️ Quick search by title, author, or ISBN with validation checks (e.g. minimum text length, 13-digit ISBN requirement).

• 🔍 Advanced search and filter by year, rating, price, publisher, category, etc. Results are ranked by relevance and rating, with book detail pages showing metadata, cover, and reader reviews.

3. Personal Collections

• 📚 Registered users can create a personal bookshelf, "My List", to organize their favorite books. Adding or removing items anytime.

4. Similar Recommendations

• ❤️ On each book detail page, "You Might Also Like" section suggests related books with similar themes, authors, or content (via semantic search).

5. Full-Stack Architecture

• 🖥️ Backend APIs – RESTful endpoints built with FastAPI + Pydantic, connecting to a PostgreSQL database. 👉 Backend API

• 🎨 Frontend UI – Responsive React interface with dynamic components (grids, filters, hover effects, book cards). Designed in Figma with user-friendly layouts. 👉 Frontend & UI design

• 🗄️ Database — A normalized PostgreSQL schema (3NF) with junction tables for many-to-many relationships. Supports efficient joins, aggregated views, and complex SQL queries. Semantic similarity search powered by FAISS(Facebook AI Similarity Search) with Sentence-BERT embeddings. 👉 Database Docs

• 🔐 Authentication – Secure sign-up/login with JWT tokens, where each user account is identified by a UUID (uuid4). Tokens include user id, issue time, and expiration, only authorized users can manage their profile.

6. Data Engineering & Ops

• 📂 Integrated Data Sources – Combines Amazon Books and Book-Crossing raw data into a unified datasets. Large-scale metadata joins and review aggregation.

• 🧹 Processing & Normalization – Cleaning, merging, handling missing values, data standardization, book title canonicalization, and author deduplication, etc.

• ⚙️ Feature Engineering – Sentence-BERT embeddings, FAISS vector index for semantic similarity, and sentiment scoring (positivity/negativity with VADER + GPT for multilingual reviews). 👉 Data Processing Docs

🔧 Tech Stack

• Frontend: React, HTML, CSS, JavaScript
• Backend: FastAPI, JWT, Pydantic, Pytest, Postman
• Database: PostgreSQL
  • Vector Search: FAISS (Facebook AI Similarity Search)
  • Data Processing: Python, Pandas, scikit-learn, Google Colab
• Version Control: Git, GitHub
• Recommendation System:
  • Retrieval-Augmented Generation (RAG) pipeline
  • Sentence-BERT embeddings
  • GPT + Ollama LLM
  • VADER sentiment analysis
  • FAISS (Facebook AI Similarity Search)
• Deployment: Docker, Docker Compose for DevOps

📁 Project Structure

root/
│
├── reading-bee-data-private/         ← Data repository (separate)
│   ├── *.csv                         ← Book metadata CSVs
│   ├── description_embeddings.npy
│   └── description_index.faiss
│
│
└── reading-bee/
    │
    ├── backend/                ← FastAPI backend service
    │   ├── routes/             ← API route handlers
    │   ├── main.py             ← App entry point
    │   ├── db.py               ← Database connection
    │   └── ...
    │
    ├── frontend/               ← React frontend app
    │   ├── assets/             ← Static assets
    │   ├── components/         ← Source code (JSX, CSS)
    │   ├── index.html          ← Main entry point for the website
    │   └── ...
    │
    ├── database/               ← SQL scripts and schema
    │
    ├── docker/                 ← Docker-related configs
    │   └── ...
    │
    ├── data/                   ← raw data and processing notebooks
    │   ├── raw/                ← Raw data files
    │   ├── data-processing/    ← Data analysis and processing
    │   └── ...
    │
    ├── docker-compose.yml      ← Main Docker Compose config
    ├── start_dev.sh            ← Development launcher script
    └── README.md               ← Project overview

🚀 Getting Started

This project uses Docker + Ollama for local development and LLM, please follow the instructions below.

✅ Step 1: Clone the repository:

Cloning the data repo:

git clone https://github.com/Chengyuli33/reading-bee-data-private.git
cd ..

Cloning the main Reading Bee repo:

git clone https://github.com/Chengyuli33/reading-bee.git
cd reading-bee

⚠️ Check: reading-bee-data-private/ should be placed under the same root as the reading-bee/ folder:

root/
├── reading-bee 
└── reading-bee-data-private

🧰 Step 2: Install Prerequisites if needed (macOs)

Download Docker Desktop to run containers locally:

brew install --cask docker

Download Ollama LLM:

brew install ollama

Then, start Docker Desktop manually:

⌘ + Space → Docker

Start Ollama service in background and pull the model (first time only):

ollama serve &
ollama pull llama3

This will download and launch the llama3 model (1st time ≈ 4GB, may take a few mins)

🐳 Step 3: Start local services

# Make the script executable
chmod +x start_dev.sh

# Run the development environment
./start_dev.sh

You will see the following logs if everything is running smoothly:

🌟 Welcome to Reading Bee Dev Environment!
🐝 Starting up...
✅ Ollama service is already running
✅ llama3 model ready
🐳 Starting Docker services...
🔁 Using docker compose (v2+)
[+] Building 
[+] Running 7/7
...
✨ All services started!

🌐 Step 4: Access the App in Browser

📱 Frontend Website: http://localhost:3000
🔧 Backend FastAPI: http://localhost:8000/docs
🤖 Ollama: http://localhost:11434

🔧 Troubleshooting

If you see port conflicts:

# Check what's using the port
lsof -i :3000  # or :8000, :5432

# Stop existing containers
docker compose down

🧪 Testing the Setup

After starting all services, verify everything works:

Database Test

docker exec -it readingbee-db psql -U postgres -d reading_bee \
  -c "SELECT COUNT(*) FROM all_book_full_details_view;"

Expected output: 273225

Backend API Test

Visit http://localhost:8000/docs or use curl:

curl "http://localhost:8000/books/search?title=harry+potter" | jq

Expected output: JSON with a total of 25706 book search results.

Frontend Test

Open http://localhost:3000 in the browser.

Ollama Test

curl http://localhost:11434/api/tags

Should return list of models {"models": ...} including llama3.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.