BookVerse

AI-Powered Full-Stack Book E-Commerce Platform
Semantic search · Personalized recommendations · Admin MIS dashboard

---

Demo

Click the thumbnail or button above to watch the full walkthrough on YouTube.

---

Overview

BookVerse is a production-grade full-stack e-commerce platform for books, powered by AI/ML. It features hybrid semantic search using sentence-transformers embeddings, a personalized recommendation engine with multi-signal preference vectors, a complete Admin MIS dashboard with 16 real-time KPIs, and a full e-commerce workflow — cart, checkout, order tracking, reviews, wishlist/reading list, and role-based access control.

---

Key Features

AI & Personalization

Feature	Description
🔍 Hybrid Semantic Search	384-dim vector embeddings (all-MiniLM-L6-v2) fused with keyword search (65% vector + 35% keyword) with 10-min caching
🎯 Personalized Recommendations	5-signal blend: preference vectors (29-dim), recency-weighted activity, collaborative filtering, content similarity, trending fallback
📖 For You Feed	Trending scorer with exponential decay (half-life 3 days), personalized carousels with explanation text
🧠 Cold-Start Quiz	Book Guide onboarding builds a 29-dim user preference vector across 15 genres, 4 moods, 3 levels, 3 lengths, 4 intents
🔗 Semantic Similarity	Embedding-based "Similar Books" with human-readable genre/category explanations
⚡ In-Memory Vector Store	Auto-rebuilding BookMatrixStore (N×29 float32) on model signals; zero-cold-start on server restart

E-Commerce

Feature	Description
📚 50+ Books, 14 Categories	Seeded with real titles across Fiction, Science, Programming, AI/ML, Business, Self-Help, and more
🛒 Full Cart & Checkout	useReducer-based cart, atomic stock deduction via select_for_update, discount integration
📦 Order Lifecycle	6 statuses (pending → delivered/cancelled), estimated delivery dates, order tracking page
💳 Discount Engine	Percentage/fixed-amount discounts with date-range validation, auto-status (Active/Scheduled/Expired)
⭐ Reviews & Ratings	Per-user-per-book unique reviews, admin moderation, order-based review prompts
❤️ Wishlist / Reading List	Bookmark with personal notes and reading completion tracking, optimistic UI updates

Admin & Operations

Feature	Description
📊 MIS Dashboard	16 KPIs: total sales, orders, books, low-stock alerts, best-seller, category-sales distribution, orders-by-status chart, recent orders
⚙️ Full CRUD Panels	Books, categories, authors, discounts — with role-guarded admin views
📋 Order Management	Status updates, customer details, expandable line items
💬 Contact Management	Threaded admin replies, read/unread tracking, user notification on reply
🔔 Notification System	8 notification types (welcome, order confirmed, order status, contact reply, discount, review approved); 15s client polling

Auth & Security

Feature	Description
🔐 Token Authentication	DRF authtoken with localStorage persistence
👥 3 Roles	Guest (browsing), User (orders, wishlist, reviews), Admin (dashboard, CRUD, management)
🔑 Password Reset	Token-based 1-hour expiry flow
🛡️ Rate Limiting	In-memory per-IP rate limiter for search (20/60s) and autocomplete (30/60s)

---

Tech Stack

Frontend

Layer	Technology	Purpose
Framework	React 19 + Vite 8	Modern concurrent rendering, instant HMR
Routing	react-router-dom v7	Layout routes with auth-guarded outlet groups
Styling	Tailwind CSS 3.4 + Radix UI	Utility-first design system, 26 hand-built components
State	Context API (4 contexts)	Auth, Cart (useReducer), Wishlist (optimistic), Theme
Icons	Lucide React	Consistent 24px iconography
Build	Vite 8	~540ms builds, ~445KB JS, ~35KB CSS

Backend

Layer	Technology	Purpose
Framework	Django 6.0 + DRF 3.14	Mature REST framework with token auth
Database	PostgreSQL 16 (default) / SQLite (dev)	Swappable via BOOKVERSE_DB env var
ML / NLP	sentence-transformers 3.0	all-MiniLM-L6-v2 — 384-dim semantic embeddings
Math	NumPy + scikit-learn	Vector ops, cosine similarity, matrix management
CORS	django-cors-headers	Development CORS policy

AI/ML Stack

Component	Technology	Detail
Embedding Model	all-MiniLM-L6-v2	384-dim, SentenceTransformer, lazy-loaded
Feature Space	Custom 29-dim vector	15 genres + 4 moods + 3 levels + 3 lengths + 4 intents
Vector Store	In-memory BookMatrixStore	N×29 float32, auto-rebuilds on post_migrate + signals
Trending	Recency-weighted decay	7-day window, half-life 3 days, hourly refresh
Scoring	Dot product + 5% popularity boost	Preference vector × feature matrix
Search Fusion	Weighted hybrid	65% vector cosine similarity + 35% keyword BM25-style

---

Architecture

┌────────────────────────────────────────────────────────────┐
│                    FRONTEND (Vite 8)                        │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────┐ │
│  │  Pages   │  │Components │  │ Contexts │  │  API      │ │
│  │  (26)    │  │ (34)      │  │  (4)     │  │  Service  │ │
│  └────┬─────┘  └─────┬─────┘  └────┬─────┘  └─────┬─────┘ │
│       └──────────────┴──────────────┴──────────────┘       │
│                        │  axios fetch (proxy /api)          │
└────────────────────────┼───────────────────────────────────┘
                         │
┌────────────────────────┼───────────────────────────────────┐
│              DJANGO REST FRAMEWORK                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   API Layer (52 endpoints)          │   │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────┐           │   │
│  │  │   api    │ │ semantic │ │ for_you   │           │   │
│  │  │ (CRUD)   │ │ (search) │ │ (feed)    │           │   │
│  │  └────┬─────┘ └────┬─────┘ └─────┬─────┘           │   │
│  │       └────────────┼─────────────┘                  │   │
│  │              ┌─────┴─────┐                          │   │
│  │              │recommend. │                          │   │
│  │              │(training) │                          │   │
│  │              └───────────┘                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                         │                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 AI / ML Layer                        │   │
│  │  ┌──────────────┐  ┌─────────────┐                 │   │
│  │  │  Embedder    │  │  Vectorizer │  BookMatrix     │   │
│  │  │(384-d model) │  │  (29-d)     │  Store(N×29)     │   │
│  │  └──────┬───────┘  └──────┬──────┘                 │   │
│  │         └─────────────────┘                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                         │                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 PostgreSQL / SQLite                  │   │
│  │  15 models · 12 indexes · Atomic stock (FOR UPDATE)  │   │
│  └─────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

---

Notable Technical Implementations

Hybrid Semantic Search

• Embedding model: all-MiniLM-L6-v2 (384-dim, SentenceTransformers) — lazy-loaded on first request with graceful fallback
• Query enrichment: Book text built from title | author | category | description | genres | mood | intent | level | length
• Fusion algorithm: Raw keyword match (ILIKE on 5 fields) weighted at 35%, vector cosine similarity at 65%
• Filters: category, author, price range, stock level; sort by relevance, newest, popularity, price, rating, title
• Caching: 10-minute LocMemCache per unique param signature; autocomplete cached 30 minutes
• Rate limiting: 20 req/60s search, 30 req/60s autocomplete (in-memory per-IP)

Personalized Recommendation Engine

• 5-signal blend:
  1. Preference vector (29-dim from cold-start quiz)
  2. Activity vector (recency-weighted interactions; half-life 7 days; view=1, cart_add=2, purchase=4)
  3. Collaborative filtering (similar users via interaction overlap)
  4. Content similarity (embedding-based "similar to past purchases")
  5. Trending fallback (for cold-start / unauthenticated users)
• Blending: 60% preference + 40% activity when both exist
• Scoring: Dot product + 5% popularity boost → top-N
• Explanation engine: Human-readable "why this was recommended" (genre match, level match, intent match)

Admin MIS Dashboard

• 16 computed KPIs via single optimized aggregation query
• Metrics: total sales, total orders, total books, low-stock count, orders-by-status breakdown, discounts given, best-seller (title + units + revenue), top 5 books, category sales distribution, recent orders
• Frontend renders: 3 KPI card groups (financial, inventory, delivery), best-seller spotlight, top-5 table, status distribution bar chart, category sales bar chart, low-stock alerts, recent orders table

Atomic Stock Deduction

• Orders use select_for_update() row-level locking to prevent oversell under concurrency
• F() expressions for atomic decrement: Book.objects.filter(id=book_id).update(stock=F('stock') - qty)
• Rollback-safe: failures at any point release the lock

Wishlist with Optimistic UI

• React Context with useReducer — immediately reflects UI changes before server confirmation
• Rollback on error: stale snapshot restored if API call fails
• Supports personal notes and reading completion (is_finished) per item

---

User Roles & Flows

👤 Guest

Browse → Search (semantic + keyword) → View details → See trending → Register

👥 Authenticated User

Browse → Search → Purchase (cart → checkout → order) → Track order → Write review → Manage wishlist/reading list → Get personalized recommendations → Manage profile → Contact support

🛡️ Admin

Full CRUD (books, categories, authors, discounts) → Manage orders (status updates) → MIS Dashboard (16 KPIs with charts) → Moderate reviews → Reply to contacts → View all notifications

---

Project Statistics

Metric	Count
Frontend Pages	26 (13 public, 6 auth-guarded, 7 admin)
UI Components	34 (18 base + 9 feature + 7 layout/shared)
API Endpoints	52
Backend Apps	5 (api, semantic, for_you, recommendations, bookstore)
Database Models	15 (UserProfile, Book, Author, Category, Order, OrderItem, Discount, Review, WishlistItem, Notification, ContactMessage, PasswordResetToken, UserInteraction + User, Token)
Serializers	25
Views / ViewSets	40+
Seed Data	50+ books · 14 categories · unique authors
Embedding Dimension	384 (semantic) + 29 (feature)
Frontend Bundle	~445KB JS · ~35KB CSS · ~540ms build
Caching Layers	4 (search 10m, autocomplete 30m, trends 1h, general 15m)

---

Setup & Installation

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 14+ (optional; SQLite works out-of-the-box for evaluation)

Quick Start

# 1. Backend
cd backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py seed_data                     # 50+ books across 14 categories
python manage.py generate_embeddings --all     # Build 384-dim semantic vectors
python manage.py runserver

# 2. Frontend (separate terminal)
cd frontend
npm install
npm run dev

• Frontend → http://localhost:5173
• Backend API → http://localhost:8000/api/

Using PostgreSQL

export BOOKVERSE_DB=postgres
export DB_NAME=bookverse DB_USER=bookuser DB_PASSWORD=1234 DB_HOST=localhost DB_PORT=5432
python manage.py runserver

Or use the included run.sh (configures PostgreSQL automatically).

Management Commands

Command	Purpose
seed_data	Populates 50+ books, 14 categories, authors
generate_embeddings	Generates 384-dim semantic embeddings (single/batch/all)
refresh_trending	Rebuilds in-memory trending scores

---

License

MIT

---

Built with React, Django, and a lot of coffee · @AdnanZaman