📚 BookLens

AI-powered book recommendations from a single photo. Point your camera at a bookshelf, get a personalised pick in under 5 seconds.

---

Features

• 📷 Visual book recognition — photograph any bookshelf, display table, or stack of books
• 🤖 Gemini Vision identifies every visible title and author from the image
• ✨ Personalised ranking — your reading history shapes every recommendation
• 💬 AI explanations — know why a book was picked, not just what
• 🎯 Cold-start quiz — new users get great recommendations after 3 quick questions
• 📖 Reading log — track status (read / reading / want to read), star ratings, and reviews
• 👤 Profile & stats — total books read, average rating, top genres, books this year
• 🌐 Web + Mobile — Next.js 14 web app and Expo React Native mobile app from one codebase

---

Tech Stack

Layer	Technology
Web frontend	Next.js 14 (App Router) + Tailwind CSS
Mobile	Expo (React Native) + NativeWind
Backend API	Python · FastAPI
Auth & Database	Supabase (Postgres + pgvector + Auth + Storage)
AI Vision	Google Gemini 2.5 Flash
AI Embeddings	Google Gemini gemini-embedding-001 (768-dim)
Book Metadata	Google Books API
Deployment	Render (backend) · Vercel (web) · Expo EAS (mobile)

---

Prerequisites

Tool	Version
Node.js	20+
pnpm	9+
Python	3.11+
Supabase CLI	1.100+
Docker Desktop	Latest (for local Supabase)
Expo CLI	Latest (npx expo)

---

Environment Variables

All secrets live in .env files that are never committed.

Backend (backend/.env)

Variable	Description
GEMINI_API_KEY	Google AI Studio key — backend only
SUPABASE_URL	Your Supabase project URL
SUPABASE_SERVICE_KEY	Supabase service role key — backend only, never expose to client
GOOGLE_BOOKS_API_KEY	Google Books API key (free tier, 1000 req/day)

Web (apps/web/.env.local)

Variable	Description
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL (public)
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key (public, enforced by RLS)
NEXT_PUBLIC_API_URL	Backend URL (http://localhost:8000 locally)

Mobile (apps/mobile/.env)

Variable	Description
EXPO_PUBLIC_SUPABASE_URL	Supabase project URL
EXPO_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key
EXPO_PUBLIC_API_URL	Backend URL (http://10.0.2.2:8000 for Android emulator)

Copy the .example files to get started:

cp backend/.env.example backend/.env
cp apps/web/.env.local.example apps/web/.env.local
cp apps/mobile/.env.example apps/mobile/.env

---

Local Development Setup

# 1. Clone the repo and install dependencies
git clone https://github.com/your-org/booklens.git && cd booklens
pnpm install

# 2. Start the local Supabase stack (requires Docker)
supabase start && supabase db reset

# 3. Copy env files and fill in your API keys
cp backend/.env.example backend/.env
cp apps/web/.env.local.example apps/web/.env.local

# 4. Start the FastAPI backend
cd backend && python -m uvicorn main:app --reload --port 8000

# 5. Start the Next.js web app (in a new terminal)
pnpm --filter @booklens/web dev

Local URLs:

• Web: http://localhost:3000
• Backend API: http://localhost:8000
• API docs (Swagger): http://localhost:8000/docs
• Supabase Studio: http://localhost:54323

---

Architecture Diagram

graph TD
    A[User: Web / Mobile] -->|Image upload| B[FastAPI Backend]
    B -->|Multipart image| C[Gemini 2.5 Flash\nVision API]
    C -->|Book list JSON| B
    B -->|Title + author| D[Google Books API]
    D -->|Enriched metadata| B
    B -->|Cache books| E[(Supabase Postgres\n+ pgvector)]
    B -->|Fetch taste vector| E
    B -->|Top-5 candidates| F[Gemini 2.5 Flash\nRecommendation API]
    F -->|Ranked + explained| B
    B -->|Results| A
    A -->|Auth| G[Supabase Auth]
    G -->|JWT| A

Loading

---

API Reference

The FastAPI backend auto-generates interactive API docs. Run the backend locally and visit: http://localhost:8000/docs

Key endpoints:

Method	Path	Description
GET	/health	Health check
POST	/vision/identify	Identify books from an image
POST	/recommend	Get personalised ranked recommendations
POST	/quiz/recommend	Recommendations from cold-start quiz answers
GET	/books/{id}	Fetch book metadata (cached or live)
POST	/users/{id}/log	Create a reading log entry
PUT	/users/{id}/log/{log_id}	Update rating / review / status
GET	/users/{id}/profile	Reading stats and profile data

---

Database Schema

See supabase/README.md for migration instructions and a full schema overview.

---

Running Tests

# Backend (pytest)
cd backend && pytest tests/ -v

# Web (Vitest)
pnpm --filter @booklens/web test

# E2E (Playwright)
pnpm --filter @booklens/web test:e2e

---

Deployment

TODO: Fill in deployment steps once hosting is configured (Phase 6).

Backend → Render

TODO

Web → Vercel

TODO

Mobile → Expo EAS

TODO

---

Contributing

1. Branch from develop: git checkout -b feature/BL-XX-short-description
2. Follow Conventional Commits: type(scope): description [BL-n]
3. Open a PR into develop. Require 1 review before merge.
4. PRs to main are for releases only.

---

Roadmap

Future modules planned on top of the BookLens platform:

• Community reviews and public shelves
• Letterboxd-style activity feed
• Monthly book club scheduler
• Barcode (ISBN) scanning
• Personalised push notifications

---

License

MIT — see LICENSE.