# internetarchive/bookreader architecture

> Architecture diagram of the GitHub repository internetarchive/bookreader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/internetarchive/bookreader
- Repository: https://github.com/internetarchive/bookreader

## Overview

##### Project Type and Purpose
- This is an open-source, browser-based JavaScript library (BookReader v5) that renders paginated content (books) in a viewer.
- It combines a core rendering engine (jQuery-based), a Web Components layer for side navigation (LitElement), and a plugin system to extend functionality (search, TTS, resume, etc.).
- It ships as an NPM package and is deployed on archive.org, with demo HTML pages, CI/CD, and a comprehensive test suite.

##### Main Components
a. Core Engine (src/BookReader & jQuery)
- Responsible for layout modes (1-up, 2-up, gallery), page drawing, scrolling, resizing, history management.
- Exports a BookReader API emitting CustomEvents (events.js).
b. BookNavigator (src/BookNavigator & LitElement)
- Listens to core’s CustomEvents.
- Implements side-panel web components (bookmarks, search, downloads, visual adjustments, sharing).
c. Plugin Layer (src/plugins)
- Mixins augment the core prototype to add features: autoplay, search UI, IIIF support, iframe embedding, TTS, URL syncing, resume.
- Each plugin registers event handlers and public API hooks.
d. Demo Harness (BookReaderDemo + index.html)
- Static HTML + JS demos illustrating usage patterns (simple embed, full, IIIF, multi-volume, iframe).
e. Build & Tooling
- Node.js build pipeline: Babel, Webpack (webpack.config.js), scripts/preversion.js, scripts/postversion.js.
- Config files: babel.config.cjs, jsconfig.json, netlify.toml.
- CI workflows (.github/workflows/node.js.yml, npm-publish.yml).
f. Testing
- Unit tests (Jest under tests/jest).
- End-to-end tests (TestCafe under tests/e2e).
- Test harness helpers and CI integration with codecov.

##### Relationships & Data Flows
- Core Engine emits CustomEvents → BookNavigator components subscribe and update UI.
- Plugins hook into Core Engine events and public methods → extend behavior.
- Build pipeline consumes src/, outputs bundled assets (JS, CSS) → deployed via Netlify and published to NPM.
- Demo pages fetch built assets → user interactions drive Core Engine + Plugins.
- Tests drive Core Engine and Plugin APIs → validate event flows and rendering.
- External Services: optional IIIF manifest fetch (demo-iiif.html), Internet Archive search API.

##### Architectural Patterns
- Hybrid MVC/Event-Driven: Core acts like a Model/View engine publishing events; Navigator acts as the Controller/View for side UI.
- Plugin/Mixin: decoupled feature modules augment core behavior.
- Web Components: LitElement-based encapsulation of UI panels.
- Build & CI/CD: automated bundling, versioning, testing, publishing.

Layer 1: User / Browser
- Demo HTML / Archive.org embed
Layer 2: BookReader Runtime
- Core Engine (jQuery)
- Plugins (search, TTS, iframe, resume…)
- BookNavigator Web Components
Layer 3: Build, Packaging & Deployment
- Webpack / Babel → dist bundle
- Netlify / NPM publish
- GitHub Actions CI
Layer 4: Testing
- Jest (unit)
- TestCafe (e2e)
Layer 5: External Dependencies
- IIIF manifest endpoints
- Internet Archive search API
- Browser APIs (CustomEvent, postMessage)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "User / Browser"
    DemoHTML["Demo HTML Pages"]:::demo
    ArchiveEmbed["Archive.org Embed"]:::demo
  end

  subgraph "BookReader Runtime"
    CoreDir["Core Engine (src/BookReader)"]:::core
    EntryPoint["Core Entry Point"]:::core
    JQuery["jQuery Wrapper"]:::core
    NavigatorDir["BookNavigator Components"]:::navigator
    PluginsDir["Plugin Layer"]:::plugin

    EntryPoint -->|imports| CoreDir
    EntryPoint -->|uses| JQuery
    EntryPoint -->|initializes| NavigatorDir
    EntryPoint -->|registers| PluginsDir
    CoreDir -->|emits events| NavigatorDir
    CoreDir -->|emits events| PluginsDir
    NavigatorDir -->|invokes| CoreDir
    PluginsDir -->|hooks/mixins| CoreDir
  end

  subgraph "Build & Packaging & Deployment"
    Babel["Babel"]:::build
    Webpack["Webpack"]:::build
    VersionScripts["Versioning Scripts"]:::build
    CI["GitHub Actions CI"]:::ci
    Dist["dist Bundle"]:::build
    Netlify["Netlify Deployment"]:::deploy
    NPM["NPM Publish"]:::deploy

    Babel -->|transpiles| Webpack
    VersionScripts -->|pre/post| Webpack
    CI -->|runs workflows| Webpack
    Webpack -->|bundles| Dist
    Dist -->|deployed| Netlify
    Dist -->|published| NPM
    CI -->|publishes| NPM
  end

  subgraph "Testing"
    Jest["Unit Tests (Jest)"]:::test
    TestCafe["E2E Tests (TestCafe)"]:::test

    Jest -->|tests| CoreDir
    Jest -->|tests| NavigatorDir
    Jest -->|tests| PluginsDir
    TestCafe -->|tests| DemoHTML
  end

  subgraph "External Dependencies"
    IIIF["IIIF Manifest Endpoints"]:::external
    IASearch["Internet Archive Search API"]:::external
    BrowserAPI["Browser APIs"]:::external

    DemoHTML -->|fetch manifest| IIIF
    DemoHTML -->|calls| IASearch
    PluginsDir -->|postMessage| BrowserAPI
  end

  click CoreDir "https://github.com/internetarchive/bookreader/tree/master/src/BookReader"
  click EntryPoint "https://github.com/internetarchive/bookreader/blob/master/src/BookReader.js"
  click JQuery "https://github.com/internetarchive/bookreader/blob/master/src/jquery-wrapper.js"
  click NavigatorDir "https://github.com/internetarchive/bookreader/tree/master/src/BookNavigator"
  click PluginsDir "https://github.com/internetarchive/bookreader/tree/master/src/plugins"
  click DemoHTML "https://github.com/internetarchive/bookreader/tree/master/BookReaderDemo"
  click Webpack "https://github.com/internetarchive/bookreader/blob/master/webpack.config.js"
  click Babel "https://github.com/internetarchive/bookreader/blob/master/babel.config.cjs"
  click Netlify "https://github.com/internetarchive/bookreader/blob/master/netlify.toml"
  click VersionScripts "https://github.com/internetarchive/bookreader/blob/master/scripts/preversion.js"
  click VersionScripts "https://github.com/internetarchive/bookreader/blob/master/scripts/postversion.js"
  click CI "https://github.com/internetarchive/bookreader/blob/master/.github/workflows/node.js.yml"
  click CI "https://github.com/internetarchive/bookreader/blob/master/.github/workflows/npm-publish.yml"
  click Jest "https://github.com/internetarchive/bookreader/tree/master/tests/jest"
  click TestCafe "https://github.com/internetarchive/bookreader/tree/master/tests/e2e"

  classDef core fill:#BBDEFB,stroke:#1E88E5;
  classDef navigator fill:#C8E6C9,stroke:#43A047;
  classDef plugin fill:#FFF9C4,stroke:#FBC02D;
  classDef build fill:#CFD8DC,stroke:#607D8B;
  classDef deploy fill:#CFD8DC,stroke:#455A64;
  classDef ci fill:#ECEFF1,stroke:#90A4AE;
  classDef test fill:#FFE0B2,stroke:#FB8C00;
  classDef demo fill:#E1BEE7,stroke:#8E24AA;
  classDef external fill:none,stroke-dasharray:5 5;
```
