Product Specification

The full, current spec for Integral Flipbook. Click the button above to download it as Markdown.

# Integral Flipbook — Product Specification

_Last updated: July 19, 2026_

## Overview

Integral Flipbook turns a PDF into a realistic, embeddable, animated page-curl flipbook. Users upload a PDF, optionally add a mobile-optimized PDF, brand the viewer, and share a public link or paste an iframe snippet into any site (BookFunnels, WordPress, custom sites, etc.).

## Goals

- Give book authors and marketers a fast, unlimited, self-serve alternative to expensive flipbook services (e.g. Paperturn).
- Realistic 3D page-turn on desktop and mobile.
- Zero-friction sharing: public link + copy-paste iframe.
- Per-book branding and reader analytics.

## Tech stack

- **Frontend:** React 19, TanStack Start v1 (SSR), TanStack Router (file-based), Tailwind CSS v4.
- **Flipbook engine:** `page-flip` (StPageFlip) — realistic 3D curl, drag-to-turn, click, swipe, keyboard, double-page spreads on desktop.
- **PDF rendering:** `pdfjs-dist` runs in the browser and rasterizes each page to JPEG at upload time — the viewer never touches the PDF.
- **Backend:** Lovable Cloud (Postgres + Storage + Auth). RLS enabled on every table.
- **Hosting:** Cloudflare Workers via TanStack Start.

## Data model

- `books` — id, owner_id, title, slug, theme JSON (colors, logo, hide-branding), created_at.
- `book_pages` — book_id, variant ('desktop' | 'mobile'), page_number, image_url. One row per rendered page per variant.
- `book_toc` — book_id, title, page_number (auto-extracted from PDF outline).
- `book_events` — book_id, session_id, event_type ('open' | 'page_view' | 'close'), page_number, user_agent, timestamp.
- Storage buckets: `flipbook-pages` (public rendered images), `flipbook-assets` (logos).

## Auth

- Email + password sign-in via Lovable Cloud.
- `auto_confirm_email` = true (no email confirmation).
- HIBP password strength check disabled.
- No anonymous sign-ups. One admin account per registered user.

## Upload pipeline

1. User selects a PDF in the admin dashboard (desktop variant, optional mobile variant).
2. Browser loads PDF.js and rasterizes each page to a ~1600px JPEG (or ~800px for mobile).
3. Each page uploads to `flipbook-pages` storage; rows insert into `book_pages` with the correct variant.
4. PDF outline (bookmarks) parsed to `book_toc`.
5. Progress bar reports "page X of Y".

## Viewer (`/book/:slug`)

- Renders standalone (no app chrome) — safe to iframe.
- Detects viewport width; serves the mobile variant when width < 768px if available.
- When both variants exist, a Desktop / Mobile pill toggle appears.
- Controls: prev / next buttons, keyboard arrows, click-to-turn, drag-to-turn, swipe on touch, page number readout, TOC sidebar, fullscreen.
- 1px inset black border on every page for a real-book edge.
- Applies per-book theme (background, accent) and optional logo.
- Emits open / page_view / close events to `book_events`.

## Admin dashboard

- `/admin` — list of the signed-in user's books, upload new book (desktop + optional mobile PDF), per-book stats at a glance.
- `/admin/:slug` — per-book:
  - Branding (background, accent, logo, hide "Powered by").
  - Versions section: replace or delete the desktop or mobile variant independently.
  - Analytics: opens over time, unique readers, page-by-page heatmap (drop-off), average session length.
  - Embed snippet: ready-to-paste `<iframe>` for the public viewer URL.
- No hard limits on number of books per user.

## Mobile variant

- Optional per-book. Recommended source PDF size: standard smaller iPhone page (~375×667pt); scales up cleanly on larger phones.
- Stored as a separate set of pages under `variant = 'mobile'`.
- Viewer auto-selects on phone widths and offers a manual toggle when both variants exist.

## Embedding

Every book exposes:

```html
<iframe src="https://integralflipbook.com/book/YOUR-SLUG"
        width="100%" height="700" frameborder="0" allowfullscreen>
</iframe>
```

The viewer route is public and iframe-friendly (no auth, no app chrome).

## Analytics

Lightweight, first-party (no third-party trackers). Events written directly to `book_events`. The admin dashboard aggregates:

- Opens over time.
- Unique reader sessions.
- Pages viewed per session.
- Page-by-page heatmap showing where readers drop off.
- Average time on book.

## Branding / theme

Global product design follows the Integral Style Guide:

- Light foundation, near-black foreground.
- Display font: Poppins. Body: Inter.
- Hero accents: yellow #FFD329, pink #FF5CB8, mint #7CEDC0, cyan #5CE4FF, blue #387CFF.

Per-book branding lets authors override background, accent, and logo inside their own viewer.

## Routes

- `/` — marketing landing page.
- `/auth` — sign in / sign up.
- `/admin` — book list + upload.
- `/admin/:slug` — per-book admin (branding, versions, analytics, embed).
- `/book/:slug` — public flipbook viewer (embed target).
- `/spec` — this specification, downloadable as Markdown.

## Non-goals / out of scope (current version)

- Password-protected or email-gated books (planned).
- Server-side PDF rendering for very large books (300+ pages); current pipeline is browser-based.
- Download / print toggles inside the viewer.
- Team accounts and multi-user book ownership.

## Known constraints

- Very large PDFs (300+ pages, heavy images) may render slowly in the browser during upload — acceptable tradeoff for zero server-side rendering cost.
- Flipbook curl realism is excellent but not pixel-identical to Paperturn.