# hourinx/pdfcpu architecture

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

- Interactive diagram: https://gitdiagram.com/hourinx/pdfcpu
- Repository: https://github.com/hourinx/pdfcpu

## Overview

pdfcpu is a Go library and CLI for reading, validating, transforming, and writing PDF files. The principal workflow is a user invoking a CLI command, which runs a CLI operation and uses the API to process a PDF. The README also documents broad capabilities including page operations, extraction, forms, security, signatures, and document generation. Source excerpts support several internal relationships; dashed edges mark plausible links whose wiring was not shown in the sampled source.

Main entry points: [`pkg/api/api.go`](https://github.com/hourinx/pdfcpu/blob/master/pkg/api/api.go) (Go API), [`pkg/pdfcpu/model/context.go`](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/model/context.go) (PDF Context), [`pkg/pdfcpu/font/fontDict.go`](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/font/fontDict.go) (Font Processing), [`pkg/pdfcpu/read.go`](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/read.go) (PDF Reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI Commands<br/>[dispatch.go]"]
  node_cliops["CLI Operations<br/>[document_exec.go]"]
  node_api["Go API<br/>[api.go]"]
end

subgraph group_processing["PDF Processing"]
  node_read["PDF Reader<br/>[read.go]"]
  node_context["PDF Context<br/>[context.go]"]
  node_validation["PDF Validation<br/>[annotation.go]"]
  node_writer["PDF Writer<br/>[write.go]"]
end

subgraph group_features["Document Features"]
  node_operations["Page Operations<br/>[page.go]"]
  node_stamping["Stamps &amp; Watermarks<br/>[stamp.go]"]
  node_forms["Form Handling<br/>[form.go]"]
  node_formengine["Form Engine<br/>[form.go]"]
  node_creation["PDF Creation<br/>[create.go]"]
  node_signatures["Signature Tools<br/>[revocate.go]"]
end

subgraph group_support["PDF Internals"]
  node_fontdict["Font Processing<br/>[fontDict.go]"]
  node_fontinstall["Font Installation<br/>[install.go]"]
  node_fontmetrics["Core Font Metrics<br/>[standard.go]"]
  node_primitives["Layout Primitives<br/>[content.go]"]
  node_filters["Stream Filters<br/>[filter.go]"]
end

node_user(("CLI/API User"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses API"| node_api
node_cli -.->|"dispatches"| node_cliops
node_cliops -->|"invokes"| node_api
node_api -.->|"reads PDFs"| node_read
node_read -->|"decodes streams"| node_filters
node_read -.->|"builds context"| node_context
node_context -.->|"provides document state"| node_validation
node_api -.->|"writes results"| node_writer
node_api -.->|"performs transformations"| node_operations
node_api -->|"offers stamping"| node_stamping
node_stamping -.->|"updates PDF"| node_context
node_api -->|"offers form tools"| node_forms
node_forms -->|"delegates form work"| node_formengine
node_forms -->|"uses creation helpers"| node_creation
node_api -->|"creates PDFs"| node_creation
node_api -->|"offers signature tools"| node_signatures
node_fontdict -->|"uses font utilities"| node_fontinstall
node_fontdict -.->|"uses core metrics"| node_fontmetrics
node_creation -->|"uses layout primitives"| node_primitives
node_fontdict -->|"uses document model"| node_context
node_formengine -->|"renders fields"| node_primitives

click node_cli "https://github.com/hourinx/pdfcpu/blob/master/pkg/cli/dispatch.go"
click node_cliops "https://github.com/hourinx/pdfcpu/blob/master/pkg/cli/document_exec.go"
click node_api "https://github.com/hourinx/pdfcpu/blob/master/pkg/api/api.go"
click node_read "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/read.go"
click node_context "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/model/context.go"
click node_validation "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/validate/annotation.go"
click node_writer "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/write.go"
click node_operations "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/page.go"
click node_stamping "https://github.com/hourinx/pdfcpu/blob/master/pkg/api/stamp.go"
click node_forms "https://github.com/hourinx/pdfcpu/blob/master/pkg/api/form.go"
click node_formengine "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/form/form.go"
click node_creation "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/create/create.go"
click node_signatures "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/sign/revocate.go"
click node_fontdict "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/font/fontDict.go"
click node_fontinstall "https://github.com/hourinx/pdfcpu/blob/master/pkg/font/install.go"
click node_fontmetrics "https://github.com/hourinx/pdfcpu/blob/master/internal/corefont/metrics/standard.go"
click node_primitives "https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/primitives/content.go"
click node_filters "https://github.com/hourinx/pdfcpu/blob/master/pkg/filter/filter.go"

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_cli,node_cliops,node_api,node_user toneBlue
class node_read,node_context,node_validation,node_writer toneAmber
class node_operations,node_stamping,node_forms,node_formengine,node_creation,node_signatures toneMint
class node_fontdict,node_fontinstall,node_fontmetrics,node_primitives,node_filters toneRose
```

## Components

### User Interfaces

- [CLI Commands](https://github.com/hourinx/pdfcpu/blob/master/pkg/cli/dispatch.go): `pkg/cli/dispatch.go`
- [CLI Operations](https://github.com/hourinx/pdfcpu/blob/master/pkg/cli/document_exec.go): `pkg/cli/document_exec.go`
- [Go API](https://github.com/hourinx/pdfcpu/blob/master/pkg/api/api.go): `pkg/api/api.go`

### PDF Processing

- [PDF Reader](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/read.go): `pkg/pdfcpu/read.go`
- [PDF Context](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/model/context.go): `pkg/pdfcpu/model/context.go`
- [PDF Validation](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/validate/annotation.go): `pkg/pdfcpu/validate/annotation.go`
- [PDF Writer](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/write.go): `pkg/pdfcpu/write.go`

### Document Features

- [Page Operations](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/page.go): `pkg/pdfcpu/page.go`
- [Stamps & Watermarks](https://github.com/hourinx/pdfcpu/blob/master/pkg/api/stamp.go): `pkg/api/stamp.go`
- [Form Handling](https://github.com/hourinx/pdfcpu/blob/master/pkg/api/form.go): `pkg/api/form.go`
- [Form Engine](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/form/form.go): `pkg/pdfcpu/form/form.go`
- [PDF Creation](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/create/create.go): `pkg/pdfcpu/create/create.go`
- [Signature Tools](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/sign/revocate.go): `pkg/pdfcpu/sign/revocate.go`

### PDF Internals

- [Font Processing](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/font/fontDict.go): `pkg/pdfcpu/font/fontDict.go`
- [Font Installation](https://github.com/hourinx/pdfcpu/blob/master/pkg/font/install.go): `pkg/font/install.go`
- [Core Font Metrics](https://github.com/hourinx/pdfcpu/blob/master/internal/corefont/metrics/standard.go): `internal/corefont/metrics/standard.go`
- [Layout Primitives](https://github.com/hourinx/pdfcpu/blob/master/pkg/pdfcpu/primitives/content.go): `pkg/pdfcpu/primitives/content.go`
- [Stream Filters](https://github.com/hourinx/pdfcpu/blob/master/pkg/filter/filter.go): `pkg/filter/filter.go`

### Other components

- **CLI/API User**

## Connections

- CLI/API User → CLI Commands: runs commands (evidence: `README.md`)
- CLI/API User → Go API: uses API (evidence: `README.md`)
- CLI Commands → CLI Operations: dispatches
- CLI Operations → Go API: invokes (evidence: `pkg/cli/document_exec.go`)
- Go API → PDF Reader: reads PDFs
- PDF Reader → Stream Filters: decodes streams (evidence: `pkg/pdfcpu/read.go`)
- PDF Reader → PDF Context: builds context
- PDF Context → PDF Validation: provides document state
- Go API → PDF Writer: writes results
- Go API → Page Operations: performs transformations
- Go API → Stamps & Watermarks: offers stamping (evidence: `README.md`)
- Stamps & Watermarks → PDF Context: updates PDF
- Go API → Form Handling: offers form tools (evidence: `README.md`)
- Form Handling → Form Engine: delegates form work (evidence: `pkg/api/form.go`)
- Form Handling → PDF Creation: uses creation helpers (evidence: `pkg/api/form.go`)
- Go API → PDF Creation: creates PDFs (evidence: `README.md`)
- Go API → Signature Tools: offers signature tools (evidence: `README.md`)
- Font Processing → Font Installation: uses font utilities (evidence: `pkg/pdfcpu/font/fontDict.go`)
- Font Processing → Core Font Metrics: uses core metrics
- PDF Creation → Layout Primitives: uses layout primitives (evidence: `pkg/pdfcpu/create/create.go`)
- Font Processing → PDF Context: uses document model (evidence: `pkg/pdfcpu/font/fontDict.go`)
- Form Engine → Layout Primitives: renders fields (evidence: `pkg/pdfcpu/form/form.go`)