# Kitaaben — Full LLM Specification

This document provides detailed technical and product specifications for Kitaaben, for AI agents, crawlers, and researchers indexing or inspecting the system.

## 1. Overview

Kitaaben ("books" in Hindi/Urdu) is a Progressive Web App for tracking a personal reading library: cataloging books, logging page progress and reflections, reading PDF/EPUB files in-browser, and getting AI-assisted recommendations and review summaries. It has no ads, no public social feed, and no cross-user visibility — every account's library is private to that account.

Primary domain: `https://kitaaben.com`. `dev.kitaaben.com` is a development tunnel, not production, and should not be indexed. `bookwise.kitaaben.com` is a separate, unrelated application on the same parent domain.

## 2. Data Model

### Book
```typescript
export type BookStatus = 'To Read' | 'Reading' | 'Completed';

export interface Book {
  id: string;
  title: string;
  author: string;
  genre: string;
  coverGradient: string;   // Tailwind gradient classes for a generated cover
  coverImage?: string;     // Optional uploaded/linked cover image
  rating: number;          // 0–5
  review: string;
  pagesTotal: number;
  pagesRead: number;
  status: BookStatus;
  dateAdded: string;
  dateStarted?: string;
  dateCompleted?: string;
  notes?: string;          // Serialized chronological journal entries
  tags?: string[];
  totalReadingTime?: number; // minutes, accumulated from timer sessions
  readingSessions?: string;  // Serialized ReadingSession[]
  fileUrl?: string;        // Cloud-stored PDF/EPUB, Elite Premium only
  fileName?: string;
}

export interface ReadingSession {
  id: string;
  minutes: number;
  pagesReadBefore: number;
  pagesReadAfter: number;
  timestamp: string;
}
```

Books are stored in Firestore under a flat `books` collection, each document owned by a `userId` field, with security rules restricting reads/writes to the owning account.

## 3. Features

### Library
Add unlimited books on every plan, either manually (title, author, genre, page count, status, optional cover image/gradient, tags) or by importing from Open Library, which prefills title/author/page count/cover. Grid, spine-shelf, and carousel display modes are available.

### Reading Journal & Timer
Each book can carry a chronological journal of dated notes/quotes. A floating, minimizable reading-session timer (draggable, swipe-to-close) tracks elapsed minutes and page progress per session, optionally with ambient background sounds, and logs completed sessions against the book.

### Reading Insights
A calendar view surfaces daily reading activity, current/longest streaks, a "mindful pace" metric (share of sessions read at 8–45 pages/hour, a proxy for unhurried vs. skimmed reading), and a breakdown of reading activity by time of day.

### PDF/EPUB Reader
Opens a locally selected PDF or EPUB in an immersive, edge-to-edge view. Toolbar, page-turn arrows, and scrubber auto-hide after a few seconds of inactivity and reveal on tap; page-turn buttons stay tappable throughout (fading their background rather than disappearing) so navigation is never fully hidden. EPUB-specific display settings: font (serif/sans/mono), line height, margin width, and paginated vs. continuous-scroll flow. Progress syncs back to the book's `pagesRead`/`status` as you read.

### Cloud File Storage (Elite Premium)
A PDF/EPUB (up to 20MB) can be saved to cloud storage — from the Add Book form, from the Edit Book form, or via a save button inside the reader itself while reading a locally-picked file. Once saved, opening that book again loads directly from the cloud copy instead of prompting for the local file. Backed by Firebase Storage (Google Cloud Storage); served through a same-origin proxy endpoint that also uses local disk as a speed cache.

### AI Discovery (Elite Premium)
Server-side calls to Google Gemini generate personalized book recommendations based on the user's existing library, chosen genres, and a requested count, each with a short rationale.

### AI-Written Reviews (Elite Premium)
Compiles a book's logged journal entries into a structured review or summary via Gemini.

### Reminders
Optional daily email reminders (sent via Resend) and browser push notifications, each with a configurable time and timezone, nudging the user to log reading progress.

### Sharing
Generates a portrait-orientation (4:5, 800×1000px) share card with the book's cover, title, author, progress percentage, and star rating. Personal notes/reviews are intentionally excluded from shared cards.

### Offline / PWA
Installable to a device home screen or desktop. Caches library data locally and queues writes for sync once connectivity returns; a service worker (`sw.js`) handles offline asset caching and push notification display.

### Visual Themes
Three themes reskin the whole app: Vintage (default, available on the free tier), Botanical, and Royal Twilight (both Elite Premium).

## 4. Plans & Billing

- **Free**: up to 12 books, full progress tracking, journaling, cloud sync of book metadata, Vintage theme.
- **Free**: unlimited book additions, imports, and reading notes.
- **Elite Premium**: AI Discovery, AI-written reviews, unlimited Book Bites, cloud PDF/EPUB storage, catalog export, and all three themes. Monthly, yearly, or lifetime options, with a 7-day free trial. Payments and subscription management are handled by Dodo Payments (merchant of record).

## 5. Architecture

- **Frontend**: React 19 + TypeScript, built with Vite, styled with Tailwind CSS 4, icons from Lucide, animation via Motion (Framer Motion). PDF rendering via `react-pdf`; EPUB rendering via `epub.js`.
- **Backend**: A single Node.js/Express server (`server.ts`) serves both the built frontend and all `/api/*` routes, deployed on Google Cloud Run.
- **Auth & Data**: Firebase Authentication (Google sign-in only) and Firestore for real-time data sync, with Firestore security rules enforcing per-user ownership and field-level validation on writes.
- **AI**: Google Gemini via the `@google/genai` SDK, called server-side only (the API key is never exposed to the client).
- **Storage**: Firebase Storage (Google Cloud Storage) for cloud-saved book files, gated to Elite Premium accounts.
- **Email**: Resend for transactional/reminder emails.
- **Analytics**: PostHog, client-side, for product usage analytics (not ad tracking).

## 6. Release History

Chronological release notes, covering feature launches and fixes, are published at `/release-notes`.