# mozilla/pdfjs-dist architecture

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

- Interactive diagram: https://gitdiagram.com/mozilla/pdfjs-dist
- Repository: https://github.com/mozilla/pdfjs-dist

## Overview

##### Project type and purpose
- PDF.js is an open-source JavaScript library for parsing and rendering PDF files in web and Node environments.
- It targets both modern platforms (ES6+) and legacy environments (see legacy/).
- The distribution includes a pre-built package (build/), a modular source tree (lib/), CMap assets, image decoders, web viewer UI, and TypeScript definitions.

##### File structure
- Top-level directories:
– build/              → pre-built bundles (pdf.js, pdf.worker.js, sandbox, maps)
– cmaps/              → binary CMap files for character mapping
– image_decoders/     → JPEG, JPX, JBIG2 decoders
– legacy/             → ES5-compatible builds and web viewer
– lib/                → modular source code split into core, display, shared, examples, tests
– standard_fonts/     → built-in Type 1 fonts
– types/              → .d.ts definitions mirroring lib/ structure
– web/                → standalone web viewer assets
– webpack.js          → build configuration
- lib/core: PDF parsing, decryption, font & stream handling, XFA support
- lib/display: rendering layers (canvas, SVG, text, annotations), network and worker orchestration
- lib/shared: cross-cutting utilities (message handler, compatibility, hashing)
- Worker model: pdf.worker.js offloads parsing and operator list creation

##### README
- Confirms HTML5-based, standards-compliant PDF parser & renderer
- Mentions modern vs. legacy builds (legacy/)
- Points to NPM packaging (pdfjs-dist)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        WP["webpack.js"]:::build
        BuildDir["build/"]:::build
        Types["types/"]:::build
    end
    click WP "https://github.com/mozilla/pdfjs-dist/blob/master/webpack.js"
    click BuildDir "https://github.com/mozilla/pdfjs-dist/tree/master/build/"
    click Types "https://github.com/mozilla/pdfjs-dist/tree/master/types/"

    %% Core Module
    subgraph "Core PDF Engine"
        Core["lib/core/"]:::core
    end
    click Core "https://github.com/mozilla/pdfjs-dist/tree/master/lib/core/"

    %% Display Module
    subgraph "Display Engine"
        Display["lib/display/"]:::display
    end
    click Display "https://github.com/mozilla/pdfjs-dist/tree/master/lib/display/"

    %% Shared Utilities
    subgraph "Shared Utilities"
        Shared["lib/shared/"]:::shared
    end
    click Shared "https://github.com/mozilla/pdfjs-dist/tree/master/lib/shared/"

    %% Worker Thread
    subgraph "Worker Thread"
        WorkerSrc["lib/pdf.worker.js"]:::runtime
        WorkerBundle["build/pdf.worker.js"]:::runtime
    end
    click WorkerSrc "https://github.com/mozilla/pdfjs-dist/blob/master/lib/pdf.worker.js"
    click WorkerBundle "https://github.com/mozilla/pdfjs-dist/blob/master/build/pdf.worker.js"

    %% Web Viewer UI
    subgraph "Web Viewer UI"
        UISrc["lib/web/"]:::ui
        UIStandalone["web/"]:::ui
    end
    click UISrc "https://github.com/mozilla/pdfjs-dist/tree/master/lib/web/"
    click UIStandalone "https://github.com/mozilla/pdfjs-dist/tree/master/web/"

    %% Assets & Data
    subgraph "Assets & Data"
        CMaps["cmaps/"]:::asset
        Fonts["standard_fonts/"]:::asset
        Decoders["image_decoders/"]:::asset
    end
    click CMaps "https://github.com/mozilla/pdfjs-dist/tree/master/cmaps/"
    click Fonts "https://github.com/mozilla/pdfjs-dist/tree/master/standard_fonts/"
    click Decoders "https://github.com/mozilla/pdfjs-dist/tree/master/image_decoders/"

    %% Legacy Builds
    Legacy["legacy/"]:::legacy
    click Legacy "https://github.com/mozilla/pdfjs-dist/tree/master/legacy/"

    %% External Caller
    ExternalApp["External App"]:::external

    %% Bundling Flow
    WP --> Core
    WP --> Display
    WP --> Shared
    WP --> Decoders
    WP --> CMaps
    WP --> Fonts
    WP --> Types
    WP --> BuildDir

    %% Runtime Flow
    ExternalApp -->|"loads"| BuildDir
    BuildDir -->|"provides bundle"| PDFJS["pdf.js bundle"]:::runtime
    PDFJS -->|"uses core"| Core
    PDFJS -->|"uses display"| Display
    PDFJS -->|"uses shared"| Shared
    PDFJS -->|"loads assets"| CMaps
    PDFJS -->|"loads assets"| Fonts
    PDFJS -->|"loads assets"| Decoders
    PDFJS -->|"initializes UI"| UISrc
    UIStandalone -->|"launches viewer"| PDFJS
    PDFJS -->|"instantiates"| WorkerBundle
    WorkerBundle -->|"hosts core"| Core
    WorkerBundle -->|"communicates via postMessage"| PDFJS

    %% Styles
    classDef build fill:#dddddd,stroke:#333333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#0366d6,stroke-width:1px
    classDef display fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef shared fill:#fff3cd,stroke:#e0a800,stroke-width:1px
    classDef asset fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px
    classDef runtime fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef ui fill:#f5cff4,stroke:#6f42c1,stroke-width:1px
    classDef legacy fill:#f8d7da,stroke:#d73a49,stroke-width:1px
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
```
