📚 BookCat

Your personal reading companion — track books, read with friends, and discover your next favourite.

Demo · Features · Tech Stack · Getting Started · Deployment · Contributing · License

A modern, full-featured reading tracker with AI-powered discovery, community features, and real-time social interactions.

🎥 Demo

Live Demo: https://your-bookcat-app.netlify.app (Replace with your actual deployed URL)

Quick Start: Create an account, add your first book via ISBN scan or manual entry, and start tracking your reading journey!

📸 Screenshots

Replace the placeholders below with actual screenshots from your deployed app.

Dashboard	Library

Reading Mode	Stats

Community	Discover

✨ Features

📚 Library Management

Add books manually or by ISBN barcode scan
Track reading status: Reading, Want to Read, Completed
Log current page and total pages with auto-calculated progress
Custom tags per book (e.g. favourites, re-reading, abandoned)
Full-text book details with cover art via Google Books API

⏱️ Reading Sessions

Timed reading sessions with intent selection (Deep Focus, Casual, etc.)
Manual page updates auto-log sessions
Session history with per-book stats (time read, sessions count)

📊 Stats & Analytics

Total reading time, pages read, books completed
Daily / weekly / monthly / all-time filters
Reading streak tracker
Milestone achievements (100 pages, 10 books, yearly goals, etc.)

🎯 Reading Goal

Set a yearly reading goal in your Profile
Real-time progress bar in the sidebar updates as you complete books
Goal celebration state when target is reached

🔍 Discover

AI-powered mood-based book search (Gemini API)
NYT Bestsellers via Supabase Edge Functions
Weekly trending books
Publisher RSS feed aggregation
Daily book facts

🧠 Daily Quiz

AI-generated daily quiz about books and reading culture
Score tracking per user

🔥 Hot Takes

Community debate cards on reading habits and book culture
Agree / Disagree voting per user

🤝 Community

Send / accept friend requests
Browse a friend's full reading library
Request a book from a friend's library (creates Exchange offer)
Real-time chat with friends
Activity feed (completed books, reading sessions)

🔄 Book Exchange

Propose a book swap with any friend
Optional message and delivery method (Meet up / Mail / Digital)
Counter-offer and negotiation flow
Exchange status tracking

🔔 Notifications

Real-time bell icon in Navbar
Notifies you of: pending friend requests, incoming exchange offers, unread messages
Supabase Realtime subscriptions for instant updates

👤 Profile

Avatar upload to Supabase Storage
Username, bio, yearly reading goal
Public profile page

🛠 Tech Stack

Layer	Technology
Frontend Framework	React 18 + Vite 5
Styling	Tailwind CSS v4
Routing	React Router v6
Backend / DB	Supabase (PostgreSQL + RLS)
Auth	Supabase Auth (email/password)
Realtime	Supabase Realtime Channels
Storage	Supabase Storage (avatars)
Edge Functions	Supabase Edge Functions (Deno)
AI	Google Gemini API (mood search, quiz, hot takes, book facts)
Book Data	Google Books API, NYT Books API
Animations	Framer Motion
Icons	Lucide React
Barcode Scan	@zxing/browser
Monorepo	Turborepo
Deployment	Netlify

📁 Project Structure

BookCAT/                          # Monorepo root
├── apps/
│   └── web/                      # Main React application
│       ├── src/
│       │   ├── assets/           # Static assets (logo, images)
│       │   ├── components/       # Reusable UI components
│       │   │   ├── layout/       # Navbar, Sidebar, BottomNav, Layout
│       │   │   ├── AddBookModal.jsx
│       │   │   ├── ISBNScanner.jsx
│       │   │   ├── Readingsessionmodal.jsx
│       │   │   ├── Realtimestatswidget.jsx
│       │   │   └── ...
│       │   ├── contexts/         # React contexts (AuthContext)
│       │   ├── hooks/            # Custom hooks (useAuth)
│       │   ├── lib/              # Supabase client, utilities
│       │   ├── pages/            # Route-level page components
│       │   │   ├── Dashboard.jsx
│       │   │   ├── Library.jsx
│       │   │   ├── Stats.jsx
│       │   │   ├── Community.jsx
│       │   │   ├── Exchange.jsx
│       │   │   ├── Discover.jsx
│       │   │   ├── Quiz.jsx
│       │   │   ├── ReadingMode.jsx
│       │   │   └── Profile.jsx
│       │   ├── services/         # Supabase query functions
│       │   └── utils/            # EventBus, StatsCache
│       ├── index.html
│       ├── vite.config.js
│       └── package.json
├── packages/                     # Shared packages (lib, types, ui)
├── supabase/
│   ├── config.toml
│   ├── functions/                # Edge Functions
│   │   ├── fetch-nyt-bestsellers/
│   │   ├── fetch-publisher-feeds/
│   │   ├── generate-book-fact/
│   │   ├── generate-daily-quiz/
│   │   └── generate-hot-takes/
│   └── migrations/               # SQL migrations (001 → 016)
├── turbo.json
└── package.json

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js ≥ 18.x (Download)
npm ≥ 10.x (comes with Node.js)
Git (Download)
A Supabase account (free tier available)
(Optional) Supabase CLI for local development

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/BookCAT.git
cd BookCAT

2. Install dependencies

This project uses npm workspaces and Turborepo:

npm install

3. Configure environment variables

Create environment files for the web app:

# Create env file
cp apps/web/.env.example apps/web/.env

Edit apps/web/.env and fill in your credentials (see Environment Variables section).

4. Set up Supabase

Option A: Using Supabase Dashboard

Go to your Supabase Dashboard
Create a new project
Navigate to SQL Editor
Run each migration file in order from supabase/migrations/:
- 001_auth_setup.sql
- 002_books_table.sql
- ... through 016_community_tables.sql

Option B: Using Supabase CLI (Recommended)

# Link to your project
supabase link --project-ref your-project-ref

# Push all migrations
supabase db push

5. Enable Realtime

In your Supabase Dashboard:

Go to Database → Replication
Enable realtime for these tables:
- messages
- friendships
- exchange_offers

6. Set up Edge Functions (Optional)

For AI features and automated tasks:

# Deploy edge functions
supabase functions deploy generate-daily-quiz
supabase functions deploy generate-hot-takes
supabase functions deploy generate-book-fact
supabase functions deploy fetch-nyt-bestsellers
supabase functions deploy fetch-publisher-feeds

Set secrets for edge functions:

supabase secrets set GEMINI_API_KEY=your_gemini_api_key
supabase secrets set NYT_API_KEY=your_nyt_api_key

7. Start the development server

# Start all apps (from root)
npm run dev

# Or start just the web app
cd apps/web && npm run dev

🚀 App runs at http://localhost:5173

🔧 Environment Variables

Create apps/web/.env with the following variables:

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-public-key

# Google Books API (for book search and metadata)
VITE_GOOGLE_BOOKS_API_KEY=your-google-books-api-key

# Gemini AI (for mood search, quiz, hot takes, book facts)
VITE_GEMINI_API_KEY=your-gemini-api-key

Where to Get API Keys

Service	Instructions
Supabase	Dashboard → Project Settings → API → Copy URL & anon key
Google Books	Google Cloud Console → APIs & Services → Enable Books API → Credentials
Gemini AI	Google AI Studio → Get API Key
NYT Books	NYT Developer Portal → Create App → Get Books API Key (for edge functions)

⚠️ Security Note: Never commit .env files to version control. They are automatically ignored via .gitignore.

🌐 Deployment

Deploy to Netlify

📦 Option A — Deploy via Netlify UI (Recommended)

Push your code to GitHub
Go to app.netlify.com
Click Add new site → Import an existing project
Connect your GitHub repository
Configure build settings:

Build Settings:

Setting	Value
Base directory	(leave empty)
Build command	`cd apps/web && npm ci && npm run build`
Publish directory	`apps/web/dist`
Node version	18 or higher

Add environment variables (see Environment Variables)
Click Deploy site

💻 Option B — Deploy via Netlify CLI

# Install Netlify CLI
npm install -g netlify-cli

# Login to Netlify
netlify login

# Initialize site
netlify init

# Deploy
netlify deploy --build --prod

Deploy Supabase Edge Functions

# Deploy all functions
supabase functions deploy

# Or deploy individually
supabase functions deploy generate-daily-quiz
supabase functions deploy generate-hot-takes
# ... etc

Set Up Cron Jobs

In your Supabase Dashboard → Database → Extensions, enable pg_cron, then configure cron schedules in your migrations (already included in migrations 006, 008, 011, 012).

🗄️ Supabase Setup

Database Tables

Table	Purpose
`profiles`	User profiles (username, avatar, bio, yearly reading goal)
`books`	User book library with status, progress, tags
`reading_sessions`	Timed reading session logs
`activities`	Community activity feed events
`friendships`	Friend connections with pending/accepted state
`messages`	Direct messages between friends
`exchange_offers`	Book exchange proposals
`daily_quiz`	AI-generated daily quiz questions
`quiz_responses`	Per-user quiz answers
`book_facts`	AI-generated daily book facts
`daily_hot_takes`	AI-generated hot takes for community voting
`hot_take_votes`	Per-user vote on hot takes
`weekly_trending`	Trending books (refreshed weekly via cron)

Row Level Security

All tables have RLS enabled. Policies ensure users can only read/write their own data. Profiles and trending data are publicly readable.

Edge Functions

Function	Schedule	Purpose
`generate-daily-quiz`	Daily cron	Generates quiz via Gemini AI
`generate-hot-takes`	Daily cron	Generates hot takes via Gemini AI
`generate-book-fact`	Daily cron	Generates book fact via Gemini AI
`fetch-nyt-bestsellers`	Weekly cron	Fetches NYT Bestseller lists
`fetch-publisher-feeds`	Weekly cron	Aggregates publisher RSS feeds

Realtime

Enable Realtime on these tables in Supabase Dashboard → Database → Replication:

messages
friendships
exchange_offers

🧰 Available Scripts

Run from the monorepo root:

Command	Description
`npm run dev`	Start all apps in dev mode (Turborepo)
`npm run build`	Build all apps for production
`npm run lint`	Lint all apps

Run from apps/web/:

Command	Description
`npm run dev`	Start Vite dev server on :5173
`npm run build`	Build for production into `dist/`
`npm run preview`	Preview production build locally

🗃️ Database Migrations Reference

Migration	Description
`001_auth_setup.sql`	Profiles table, RLS, avatar storage bucket
`002_books_table.sql`	Books table with RLS and indexes
`003_library_features.sql`	Reading sessions table
`004_book_tags.sql`	Tags array column on books
`006_publisher_feeds_cron.sql`	Publisher RSS cron schedule
`007_daily_quiz.sql`	Daily quiz + responses tables
`008_daily_quiz_cron.sql`	Quiz generation cron schedule
`009_book_facts.sql`	Daily book facts table
`010_weekly_trending.sql`	Weekly trending books table
`011–012_trending_cron.sql`	Trending refresh cron
`013_fix_books_updated_at.sql`	Restore `updated_at` column + trigger
`014_hot_takes_and_active_readers.sql`	Hot takes, votes, active readers view
`015_fix_duration_minutes_default.sql`	Default value for `duration_minutes`
`016_community_tables.sql`	Friendships, messages, Realtime setup

🤝 Contributing

We welcome contributions from the community! Whether it's bug reports, feature requests, or code contributions, all are appreciated.

How to Contribute

Fork the repository

git clone https://github.com/YOUR_USERNAME/BookCAT.git

Create a feature branch
```
git checkout -b feat/amazing-feature
```
Make your changes
- Follow the existing code style
- Write clear, concise commit messages
- Add tests if applicable
- Update documentation as needed
Commit your changes
```
git commit -m "feat: add amazing feature"
```
We follow Conventional Commits:
- feat: New features
- fix: Bug fixes
- docs: Documentation changes
- style: Code style changes (formatting, etc.)
- refactor: Code refactoring
- test: Adding or updating tests
- chore: Maintenance tasks
Push to your fork
```
git push origin feat/amazing-feature
```
Open a Pull Request
- Provide a clear description of the changes
- Reference any related issues
- Wait for review and address feedback

Development Guidelines

Code Style: Follow the existing patterns in the codebase
Components: Keep components small and focused
State Management: Use React Context for global state
Styling: Use Tailwind CSS utility classes
Database: Always use Row Level Security policies
Testing: Test your changes locally before submitting

Reporting Issues

Found a bug or have a feature request?

Check if the issue already exists
If not, create a new issue
Provide as much context as possible
Include steps to reproduce (for bugs)
Add screenshots or screen recordings if applicable

🗺️ Roadmap

Future features and improvements we're considering:

Have an idea? Open an issue with the enhancement label!

💬 Support

Need help? Have questions? We're here for you!

📖 Documentation: Check this README and inline code comments
🐛 Bug Reports: Open an issue
💡 Feature Requests: Start a discussion
💬 Community: Join our Discord server (add link if available)
📧 Email: contact@bookcat.app (update with your email)

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

BookCat is built with amazing open-source technologies:

React - UI library
Vite - Build tool
Supabase - Backend platform
Tailwind CSS - Styling
Framer Motion - Animations
Lucide Icons - Icon library
Google Books API - Book data
Google Gemini - AI features
ZXing - Barcode scanning

📊 Project Stats

📝 Changelog

See CHANGELOG.md for a detailed history of changes. (Create this file if needed)

Happy Reading! 🐱📖

Made with ❤️ by the BookCat community

Back to Top ↑

Name		Name	Last commit message	Last commit date
Latest commit History 111 Commits
.turbo		.turbo
apps/web		apps/web
node_modules		node_modules
packages		packages
supabase		supabase
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
issues.md		issues.md
netlify.toml		netlify.toml
package-lock.json		package-lock.json
package.json		package.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

📚 BookCat

🎥 Demo

📸 Screenshots

✨ Features

📚 Library Management

⏱️ Reading Sessions

📊 Stats & Analytics

🎯 Reading Goal

🔍 Discover

🧠 Daily Quiz

🔥 Hot Takes

🤝 Community

🔄 Book Exchange

🔔 Notifications

👤 Profile

🛠 Tech Stack

📁 Project Structure

🚀 Getting Started

Prerequisites

1. Clone the repository

2. Install dependencies

3. Configure environment variables

4. Set up Supabase

Option A: Using Supabase Dashboard

Option B: Using Supabase CLI (Recommended)

5. Enable Realtime

6. Set up Edge Functions (Optional)

7. Start the development server

🔧 Environment Variables

Where to Get API Keys

🌐 Deployment

Deploy to Netlify

Deploy Supabase Edge Functions

Set Up Cron Jobs

🗄️ Supabase Setup

Database Tables

Row Level Security

Edge Functions

Realtime

🧰 Available Scripts

🗃️ Database Migrations Reference

🤝 Contributing

How to Contribute

Development Guidelines

Reporting Issues

🗺️ Roadmap

💬 Support

⚖️ License

🙏 Acknowledgments

📊 Project Stats

📝 Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages