# hopding/pdf-lib architecture

> Architecture diagram of the GitHub repository hopding/pdf-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hopding/pdf-lib
- Repository: https://github.com/hopding/pdf-lib

## Overview

pdf-lib is a JavaScript library for creating and modifying PDFs across runtimes. Its main workflow accepts PDF bytes or creates a document, applies page/content, form, and embedding operations, then serializes the document to bytes. The graph also includes the parser, object context, and writer as internal layers. README capabilities guide the feature branches; because most API implementations were not sampled, uncertain call wiring is omitted.

Main entry points: [`src/api/PDFDocument.ts`](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFDocument.ts) (PDFDocument), [`src/api/PDFPage.ts`](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFPage.ts) (PDFPage), [`src/api/form/PDFForm.ts`](https://github.com/hopding/pdf-lib/blob/master/src/api/form/PDFForm.ts) (Form API), [`src/core/writers/PDFWriter.ts`](https://github.com/hopding/pdf-lib/blob/master/src/core/writers/PDFWriter.ts) (PDF writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Document API"]
  node_document["PDFDocument<br/>[PDFDocument.ts]"]
  node_page["PDFPage<br/>[PDFPage.ts]"]
end

subgraph group_editing["PDF Features"]
  node_form_api["Form API<br/>[PDFForm.ts]"]
  node_form_fields["Form fields<br/>[index.ts]"]
  node_text_drawing["Text drawing<br/>[index.ts]"]
  node_image_drawing["Image drawing<br/>[index.ts]"]
  node_page_embedding["PDF page embedding<br/>[PDFEmbeddedPage.ts]"]
  node_font_embedding["Font embedding<br/>[PDFFont.ts]"]
  node_image_embedding["Image embedding<br/>[PDFImage.ts]"]
  node_attachments["Attachments<br/>[PDFEmbeddedFile.ts]"]
  node_viewer_prefs["Viewer preferences"]
end

subgraph group_core["PDF Core"]
  node_acroform["AcroForm model<br/>[PDFAcroForm.ts]"]
  node_context[("PDF object context<br/>[PDFContext.ts]")]
  node_object_copier["Object copier<br/>[PDFObjectCopier.ts]"]
end

subgraph group_io["Parsing and Output"]
  node_parser["PDF parser<br/>[PDFParser.ts]"]
  node_pdf_objects["PDF objects<br/>[PDFObject.ts]"]
  node_writer["PDF writer<br/>[PDFWriter.ts]"]
  node_stream_writer["Stream writer<br/>[PDFStreamWriter.ts]"]
end

node_developer(("JavaScript caller"))
node_pdf_input["PDF bytes"]
node_pdf_output["PDF bytes"]

node_developer -->|"calls API"| node_document
node_pdf_input -->|"loads bytes"| node_document
node_document -->|"saves bytes"| node_pdf_output
node_document -->|"manages pages"| node_page
node_document -->|"provides forms"| node_form_api
node_form_api -->|"creates fields"| node_form_fields
node_page -->|"draws text"| node_text_drawing
node_page -->|"draws images"| node_image_drawing
node_page -->|"draws PDF pages"| node_page_embedding
node_document -->|"embeds fonts"| node_font_embedding
node_document -->|"embeds images"| node_image_embedding
node_document -->|"adds attachments"| node_attachments
node_document -->|"sets preferences"| node_viewer_prefs
node_form_api -->|"uses field model"| node_acroform
node_document -->|"parses input"| node_parser
node_parser -->|"populates objects"| node_context
node_context -->|"holds objects"| node_pdf_objects
node_document -->|"copies PDF objects"| node_object_copier
node_document -->|"serializes document"| node_writer
node_writer -->|"writes streams"| node_stream_writer
node_writer -->|"emits bytes"| node_pdf_output

click node_document "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFDocument.ts"
click node_page "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFPage.ts"
click node_form_api "https://github.com/hopding/pdf-lib/blob/master/src/api/form/PDFForm.ts"
click node_form_fields "https://github.com/hopding/pdf-lib/blob/master/src/api/form/index.ts"
click node_text_drawing "https://github.com/hopding/pdf-lib/blob/master/src/api/text/index.ts"
click node_image_drawing "https://github.com/hopding/pdf-lib/blob/master/src/api/image/index.ts"
click node_page_embedding "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFEmbeddedPage.ts"
click node_font_embedding "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFFont.ts"
click node_image_embedding "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFImage.ts"
click node_attachments "https://github.com/hopding/pdf-lib/blob/master/src/api/PDFEmbeddedFile.ts"
click node_viewer_prefs "https://github.com/hopding/pdf-lib/blob/master/src/core/interactive/ViewerPreferences.ts"
click node_acroform "https://github.com/hopding/pdf-lib/blob/master/src/core/acroform/PDFAcroForm.ts"
click node_context "https://github.com/hopding/pdf-lib/blob/master/src/core/PDFContext.ts"
click node_object_copier "https://github.com/hopding/pdf-lib/blob/master/src/core/PDFObjectCopier.ts"
click node_parser "https://github.com/hopding/pdf-lib/blob/master/src/core/parser/PDFParser.ts"
click node_pdf_objects "https://github.com/hopding/pdf-lib/blob/master/src/core/objects/PDFObject.ts"
click node_writer "https://github.com/hopding/pdf-lib/blob/master/src/core/writers/PDFWriter.ts"
click node_stream_writer "https://github.com/hopding/pdf-lib/blob/master/src/core/writers/PDFStreamWriter.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_document,node_page toneBlue
class node_form_api,node_form_fields,node_text_drawing,node_image_drawing,node_page_embedding,node_font_embedding,node_image_embedding,node_attachments,node_viewer_prefs toneAmber
class node_acroform,node_context,node_object_copier toneMint
class node_parser,node_pdf_objects,node_writer,node_stream_writer toneRose
class node_developer,node_pdf_input,node_pdf_output toneIndigo
```

## Components

### Document API

- [PDFDocument](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFDocument.ts): `src/api/PDFDocument.ts`
- [PDFPage](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFPage.ts): `src/api/PDFPage.ts`

### PDF Features

- [Form API](https://github.com/hopding/pdf-lib/blob/master/src/api/form/PDFForm.ts): `src/api/form/PDFForm.ts`
- [Form fields](https://github.com/hopding/pdf-lib/blob/master/src/api/form/index.ts): `src/api/form/index.ts`
- [Text drawing](https://github.com/hopding/pdf-lib/blob/master/src/api/text/index.ts): `src/api/text/index.ts`
- [Image drawing](https://github.com/hopding/pdf-lib/blob/master/src/api/image/index.ts): `src/api/image/index.ts`
- [PDF page embedding](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFEmbeddedPage.ts): `src/api/PDFEmbeddedPage.ts`
- [Font embedding](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFFont.ts): `src/api/PDFFont.ts`
- [Image embedding](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFImage.ts): `src/api/PDFImage.ts`
- [Attachments](https://github.com/hopding/pdf-lib/blob/master/src/api/PDFEmbeddedFile.ts): `src/api/PDFEmbeddedFile.ts`
- [Viewer preferences](https://github.com/hopding/pdf-lib/blob/master/src/core/interactive/ViewerPreferences.ts): `src/core/interactive/ViewerPreferences.ts`

### PDF Core

- [AcroForm model](https://github.com/hopding/pdf-lib/blob/master/src/core/acroform/PDFAcroForm.ts): `src/core/acroform/PDFAcroForm.ts`
- [PDF object context](https://github.com/hopding/pdf-lib/blob/master/src/core/PDFContext.ts): `src/core/PDFContext.ts`
- [Object copier](https://github.com/hopding/pdf-lib/blob/master/src/core/PDFObjectCopier.ts): `src/core/PDFObjectCopier.ts`

### Parsing and Output

- [PDF parser](https://github.com/hopding/pdf-lib/blob/master/src/core/parser/PDFParser.ts): `src/core/parser/PDFParser.ts`
- [PDF objects](https://github.com/hopding/pdf-lib/blob/master/src/core/objects/PDFObject.ts): `src/core/objects/PDFObject.ts`
- [PDF writer](https://github.com/hopding/pdf-lib/blob/master/src/core/writers/PDFWriter.ts): `src/core/writers/PDFWriter.ts`
- [Stream writer](https://github.com/hopding/pdf-lib/blob/master/src/core/writers/PDFStreamWriter.ts): `src/core/writers/PDFStreamWriter.ts`

### Other components

- **JavaScript caller**
- **PDF bytes**
- **PDF bytes**

## Connections

- JavaScript caller → PDFDocument: calls API
- PDF bytes → PDFDocument: loads bytes
- PDFDocument → PDF bytes: saves bytes
- PDFDocument → PDFPage: manages pages
- PDFDocument → Form API: provides forms
- Form API → Form fields: creates fields
- PDFPage → Text drawing: draws text
- PDFPage → Image drawing: draws images
- PDFPage → PDF page embedding: draws PDF pages
- PDFDocument → Font embedding: embeds fonts
- PDFDocument → Image embedding: embeds images
- PDFDocument → Attachments: adds attachments
- PDFDocument → Viewer preferences: sets preferences
- Form API → AcroForm model: uses field model
- PDFDocument → PDF parser: parses input
- PDF parser → PDF object context: populates objects
- PDF object context → PDF objects: holds objects
- PDFDocument → Object copier: copies PDF objects
- PDFDocument → PDF writer: serializes document
- PDF writer → Stream writer: writes streams
- PDF writer → PDF bytes: emits bytes
