# libharu/libharu architecture

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

- Interactive diagram: https://gitdiagram.com/libharu/libharu
- Repository: https://github.com/libharu/libharu

## Overview

Haru is a C library for generating PDF documents, with language bindings exposing its API. The principal workflow is a caller creating a document, adding pages and content, then writing a PDF. Major documented capabilities include text, images, fonts and encodings, annotations and outlines, compression, and encryption. The graph also shows the internal PDF-object and stream layer. Internal call paths are only partly evidenced by the supplied excerpts and source index, so documented feature links are identified as such rather than presented as verified call sequences.

Main entry points: [`include/hpdf.h`](https://github.com/libharu/libharu/blob/master/include/hpdf.h) (C API), [`src/hpdf_doc.c`](https://github.com/libharu/libharu/blob/master/src/hpdf_doc.c) (Document lifecycle), [`bindings/python/hpdf.py`](https://github.com/libharu/libharu/blob/master/bindings/python/hpdf.py) (Python binding), [`src/hpdf_pages.c`](https://github.com/libharu/libharu/blob/master/src/hpdf_pages.c) (Pages and drawing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_capi["C API<br/>[hpdf.h]"]
  node_python["Python binding<br/>[hpdf.py]"]
  node_pytypes["Python types<br/>[hpdf_types.py]"]
  node_pyconstants["Python constants<br/>[hpdf_consts.py]"]
  node_ruby["Ruby binding<br/>[hpdf.c]"]
end

subgraph group_content["Document Content"]
  node_documents["Document lifecycle<br/>[hpdf_doc.c]"]
  node_pages["Pages and drawing<br/>[hpdf_pages.c]"]
  node_operators["Page operators"]
  node_annotations["Annotations<br/>[hpdf_annotation.c]"]
end

subgraph group_features["PDF Features"]
  node_fontdefs["Font definitions"]
  node_ttfonts["TrueType fonts<br/>[hpdf_fontdef_tt.c]"]
  node_encoders["Text encodings<br/>[hpdf_encoder.c]"]
  node_jpencodings["Japanese encodings<br/>[hpdf_encoder_jp.c]"]
  node_images["Images<br/>[hpdf_image.c]"]
  node_encryption["Encryption<br/>[hpdf_encrypt.c]"]
end

subgraph group_internals["PDF Internals"]
  node_streams["PDF streams<br/>[hpdf_streams.c]"]
  node_objects["PDF objects<br/>[hpdf_objects.c]"]
end

node_caller(("Library caller"))
node_pdfresult["PDF file"]

node_caller -->|"uses"| node_capi
node_caller -.->|"uses"| node_python
node_caller -.->|"uses"| node_ruby
node_python -->|"imports"| node_pyconstants
node_python -->|"imports"| node_pytypes
node_ruby -->|"calls"| node_capi
node_capi -.->|"creates PDFs"| node_documents
node_documents -.->|"writes"| node_pdfresult
node_documents -.->|"manages pages"| node_pages
node_pages -.->|"draws content"| node_operators
node_pages -.->|"adds annotations"| node_annotations
node_capi -.->|"embeds fonts"| node_fontdefs
node_capi -.->|"embeds TrueType"| node_ttfonts
node_capi -.->|"selects encodings"| node_encoders
node_encoders -.->|"supports CJK"| node_jpencodings
node_capi -.->|"embeds images"| node_images
node_capi -.->|"encrypts PDFs"| node_encryption
node_documents -.->|"serializes objects"| node_objects
node_objects -.->|"writes streams"| node_streams

click node_capi "https://github.com/libharu/libharu/blob/master/include/hpdf.h"
click node_python "https://github.com/libharu/libharu/blob/master/bindings/python/hpdf.py"
click node_pytypes "https://github.com/libharu/libharu/blob/master/bindings/python/hpdf_types.py"
click node_pyconstants "https://github.com/libharu/libharu/blob/master/bindings/python/hpdf_consts.py"
click node_ruby "https://github.com/libharu/libharu/blob/master/bindings/ruby/hpdf.c"
click node_documents "https://github.com/libharu/libharu/blob/master/src/hpdf_doc.c"
click node_pages "https://github.com/libharu/libharu/blob/master/src/hpdf_pages.c"
click node_operators "https://github.com/libharu/libharu/blob/master/src/hpdf_page_operator.c"
click node_annotations "https://github.com/libharu/libharu/blob/master/src/hpdf_annotation.c"
click node_fontdefs "https://github.com/libharu/libharu/blob/master/src/hpdf_fontdef_base14.c"
click node_ttfonts "https://github.com/libharu/libharu/blob/master/src/hpdf_fontdef_tt.c"
click node_encoders "https://github.com/libharu/libharu/blob/master/src/hpdf_encoder.c"
click node_jpencodings "https://github.com/libharu/libharu/blob/master/src/hpdf_encoder_jp.c"
click node_images "https://github.com/libharu/libharu/blob/master/src/hpdf_image.c"
click node_encryption "https://github.com/libharu/libharu/blob/master/src/hpdf_encrypt.c"
click node_streams "https://github.com/libharu/libharu/blob/master/src/hpdf_streams.c"
click node_objects "https://github.com/libharu/libharu/blob/master/src/hpdf_objects.c"

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_capi,node_python,node_pytypes,node_pyconstants,node_ruby toneBlue
class node_documents,node_pages,node_operators,node_annotations toneAmber
class node_fontdefs,node_ttfonts,node_encoders,node_jpencodings,node_images,node_encryption toneMint
class node_streams,node_objects toneRose
class node_caller,node_pdfresult toneIndigo
```

## Components

### Public API

- [C API](https://github.com/libharu/libharu/blob/master/include/hpdf.h): `include/hpdf.h`
- [Python binding](https://github.com/libharu/libharu/blob/master/bindings/python/hpdf.py): `bindings/python/hpdf.py`
- [Python types](https://github.com/libharu/libharu/blob/master/bindings/python/hpdf_types.py): `bindings/python/hpdf_types.py`
- [Python constants](https://github.com/libharu/libharu/blob/master/bindings/python/hpdf_consts.py): `bindings/python/hpdf_consts.py`
- [Ruby binding](https://github.com/libharu/libharu/blob/master/bindings/ruby/hpdf.c): `bindings/ruby/hpdf.c`

### Document Content

- [Document lifecycle](https://github.com/libharu/libharu/blob/master/src/hpdf_doc.c): `src/hpdf_doc.c`
- [Pages and drawing](https://github.com/libharu/libharu/blob/master/src/hpdf_pages.c): `src/hpdf_pages.c`
- [Page operators](https://github.com/libharu/libharu/blob/master/src/hpdf_page_operator.c): `src/hpdf_page_operator.c`
- [Annotations](https://github.com/libharu/libharu/blob/master/src/hpdf_annotation.c): `src/hpdf_annotation.c`

### PDF Features

- [Font definitions](https://github.com/libharu/libharu/blob/master/src/hpdf_fontdef_base14.c): `src/hpdf_fontdef_base14.c`
- [TrueType fonts](https://github.com/libharu/libharu/blob/master/src/hpdf_fontdef_tt.c): `src/hpdf_fontdef_tt.c`
- [Text encodings](https://github.com/libharu/libharu/blob/master/src/hpdf_encoder.c): `src/hpdf_encoder.c`
- [Japanese encodings](https://github.com/libharu/libharu/blob/master/src/hpdf_encoder_jp.c): `src/hpdf_encoder_jp.c`
- [Images](https://github.com/libharu/libharu/blob/master/src/hpdf_image.c): `src/hpdf_image.c`
- [Encryption](https://github.com/libharu/libharu/blob/master/src/hpdf_encrypt.c): `src/hpdf_encrypt.c`

### PDF Internals

- [PDF streams](https://github.com/libharu/libharu/blob/master/src/hpdf_streams.c): `src/hpdf_streams.c`
- [PDF objects](https://github.com/libharu/libharu/blob/master/src/hpdf_objects.c): `src/hpdf_objects.c`

### Other components

- **Library caller**
- **PDF file**

## Connections

- Library caller → C API: uses
- Library caller → Python binding: uses
- Library caller → Ruby binding: uses
- Python binding → Python constants: imports (evidence: `bindings/python/hpdf.py`)
- Python binding → Python types: imports (evidence: `bindings/python/hpdf.py`)
- Ruby binding → C API: calls (evidence: `bindings/ruby/hpdf.c`)
- C API → Document lifecycle: creates PDFs (evidence: `src/hpdf_doc.c`)
- Document lifecycle → PDF file: writes
- Document lifecycle → Pages and drawing: manages pages
- Pages and drawing → Page operators: draws content (evidence: `src/hpdf_page_operator.c`)
- Pages and drawing → Annotations: adds annotations (evidence: `src/hpdf_pages.c`)
- C API → Font definitions: embeds fonts
- C API → TrueType fonts: embeds TrueType
- C API → Text encodings: selects encodings (evidence: `src/hpdf_encoder.c`)
- Text encodings → Japanese encodings: supports CJK
- C API → Images: embeds images
- C API → Encryption: encrypts PDFs
- Document lifecycle → PDF objects: serializes objects
- PDF objects → PDF streams: writes streams