# bookracy/epub-converter architecture

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

- Interactive diagram: https://gitdiagram.com/bookracy/epub-converter
- Repository: https://github.com/bookracy/epub-converter

## Overview

##### Project type and purpose
- From the README and file tree, this is an NPM library (“bookracy-convertor”) that runs in a browser environment. Its sole purpose is to fetch and parse an EPUB file, then generate a PDF via jsPDF. It is not a full-stack service but an open-source client-side conversion tool (library) intended for embedding into web pages or other JS/TS projects.

##### File structure
- Top-level files:
- package.json, pnpm-lock.yaml, package-lock.json – NPM package metadata and locks
- README.md, CONTRIBUTING.md – docs
- .github/workflows/publish.yml – CI/CD pipeline for publishing to NPM/GitHub
- “src” directory: core implementation
- fetchFile.ts – retrieves the EPUB blob via HTTP or File API
- handleEpub.ts – unzips EPUB (JSZip) and extracts XHTML chapters, images, TOC
- htmlToText.ts – sanitizes and converts HTML nodes to plain text (html-to-text)
- buildPdf.ts – orchestrates jsPDF page creation, layout, fonts, images, TOC
- index.ts, main.ts – public API entry points (UMD/E SM builds)
- polyfills/node-globals.ts – environment shims for browser vs. Node
- “dist” directory: generated UMD and ESM bundles + sourcemaps
- Configuration: tsconfig.json, vite.config.ts, eslint.config.mjs
- “test” directory: minimal automated test for EPUB→PDF workflow

##### README for additional insights
- Key dependencies: jsPDF, JSZip, html-to-text
- Usage pattern: import buildPDFConvertor, supply EPUB URL and button element
- Build/test scripts via Vite, ESLint, Node v14+ requirement

##### Key takeaways
- Every discrete step in the conversion pipeline.
- Delineate build versus runtime clearly.
- How consumers integrate the library (import → button)
- Call out any environment shims/polyfills.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Conversion Pipeline"
        UI["Web UI: Generate PDF Button"]:::runtime
        HTTP["External EPUB URL"]:::external
        Converter["buildPDFConvertor (Public API Entry)"]:::runtime
        Fetch["EPUB Fetcher\n(fetchFile)"]:::runtime
        Store["In-Memory EPUB Binary"]:::runtime
        Parser["EPUB Parser\n(handleEpub)"]:::runtime
        HTML["Text Processor\n(htmlToText)"]:::runtime
        PDF["PDF Generator\n(buildPdf)"]:::runtime
        Download["Browser Download API"]:::runtime

        UI -->|"click"| Converter
        Converter -->|"calls fetchFile"| Fetch
        Fetch --> HTTP
        Fetch -->|"binary blob"| Store
        Store -->|"input"| Parser
        Parser -->|"chapters & assets"| HTML
        HTML -->|"text & images"| PDF
        PDF --> Download
    end

    subgraph "Build & Deploy Pipeline"
        Src["Source Code\n(src directory)"]:::build
        Poly["Environment Polyfills\n(node-globals)"]:::build
        ESM["ESM Entry Point\n(src/index.ts)"]:::build
        UMD["UMD Entry Point\n(src/main.ts)"]:::build
        Config["Bundler Config\n(vite.config.ts)"]:::build

        DistMJS["dist/epub-converter.mjs"]:::build
        DistMJSMap["dist/epub-converter.mjs.map"]:::build
        DistUMD["dist/epub-converter.umd.js"]:::build
        DistUMDMap["dist/epub-converter.umd.js.map"]:::build

        Test["Test Harness\n(test/epubToPdfTest.test.mjs)"]:::build
        CI["GitHub Actions\n(.github/workflows/publish.yml)"]:::build
        NPM["NPM Registry"]:::external
        PackageMeta["package.json"]:::build

        Src --> Poly
        Src --> ESM
        Src --> UMD
        Src --> PackageMeta
        Src --> Config
        Config --> DistMJS
        Config --> DistMJSMap
        Config --> DistUMD
        Config --> DistUMDMap
        DistMJS --> Test
        DistUMSMap --> Test
        DistUMD --> Test
        DistUMDMap --> Test
        CI --> DistMJS
        CI --> DistMJSMap
        CI --> DistUMD
        CI --> DistUMDMap
        CI -->|"publishes"| NPM
    end

    classDef runtime fill:#e0f0ff,stroke:#0066cc,color:#003366;
    classDef build fill:#e6ffe6,stroke:#33aa33,color:#006600;
    classDef external fill:#f0f0f0,stroke:#888888,color:#555555;

    click Fetch "https://github.com/bookracy/epub-converter/blob/main/src/fetchFile.ts"
    click Parser "https://github.com/bookracy/epub-converter/blob/main/src/handleEpub.ts"
    click HTML "https://github.com/bookracy/epub-converter/blob/main/src/htmlToText.ts"
    click PDF "https://github.com/bookracy/epub-converter/blob/main/src/buildPdf.ts"
    click ESM "https://github.com/bookracy/epub-converter/blob/main/src/index.ts"
    click UMD "https://github.com/bookracy/epub-converter/blob/main/src/main.ts"
    click Poly "https://github.com/bookracy/epub-converter/blob/main/src/polyfills/node-globals.ts"
    click Config "https://github.com/bookracy/epub-converter/blob/main/vite.config.ts"
    click CI "https://github.com/bookracy/epub-converter/blob/main/.github/workflows/publish.yml"
    click DistMJS "https://github.com/bookracy/epub-converter/blob/main/dist/epub-converter.mjs"
    click DistMJSMap "https://github.com/bookracy/epub-converter/blob/main/dist/epub-converter.mjs.map"
    click DistUMD "https://github.com/bookracy/epub-converter/blob/main/dist/epub-converter.umd.js"
    click DistUMDMap "https://github.com/bookracy/epub-converter/blob/main/dist/epub-converter.umd.js.map"
    click Test "https://github.com/bookracy/epub-converter/blob/main/test/epubToPdfTest.test.mjs"
    click PackageMeta "https://github.com/bookracy/epub-converter/blob/main/package.json"
```
