# chinapandaman/pypdfform architecture

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

- Interactive diagram: https://gitdiagram.com/chinapandaman/pypdfform
- Repository: https://github.com/chinapandaman/pypdfform

## Overview

PyPDFForm is a Python library and CLI for PDF form automation. The main workflow loads a PDF into PdfWrapper, exposes existing fields for inspection or mutation, applies supplied field values or creates content, and writes the resulting PDF. Separate CLI commands support inspection, updates, annotations, raw drawing, page extraction, and merging. Widget models and middleware represent form fields; hooks apply field-property changes to PDF annotations. The README documents several capabilities whose command implementations were not sampled, so their connections are limited to documented entry points.

Main entry points: [`PyPDFForm/lib/wrapper.py`](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/wrapper.py) (PdfWrapper), [`PyPDFForm/cli/entry.py`](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/entry.py) (CLI entry), [`PyPDFForm/lib/types.py`](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/types.py) (PDF collections), [`PyPDFForm/cli/create.py`](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/create.py) (Create commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_wrapper["PdfWrapper<br/>[wrapper.py]"]
  node_pdfarray["PDF collections<br/>[types.py]"]
end

subgraph group_cli["Command Line"]
  node_cli_entry["CLI entry<br/>[entry.py]"]
  node_cli_create["Create commands<br/>[create.py]"]
  node_cli_inspect["Inspect commands<br/>[inspect.py]"]
  node_cli_update["Update commands<br/>[update.py]"]
  node_cli_remove["Remove commands<br/>[remove.py]"]
end

subgraph group_fields["Form Fields"]
  node_field_models["Field models"]
  node_field_middleware["Field middleware"]
  node_hooks["Field hooks<br/>[hooks.py]"]
end

subgraph group_content["PDF Content"]
  node_raw_elements["Raw elements"]
  node_annotations["Annotations"]
  node_watermark["Watermark drawing<br/>[watermark.py]"]
end

subgraph group_documents["Document Operations"]
  node_pdf_docs["PDF operations<br/>[types.py]"]
end

node_developer(("Python developer"))
node_operator(("CLI user"))
node_input_pdf["Input PDF"]
node_output_pdf["Output PDF"]

node_developer -->|"calls API"| node_wrapper
node_input_pdf -->|"loads PDF"| node_wrapper
node_wrapper -->|"writes PDF"| node_output_pdf
node_wrapper -->|"loads fields"| node_field_middleware
node_field_middleware -->|"exposes state"| node_wrapper
node_wrapper -->|"triggers hooks"| node_hooks
node_operator -->|"runs commands"| node_cli_entry
node_cli_entry -->|"dispatches"| node_cli_create
node_cli_entry -->|"dispatches"| node_cli_inspect
node_cli_entry -->|"dispatches"| node_cli_update
node_cli_entry -->|"dispatches"| node_cli_remove
node_cli_create -->|"creates content"| node_wrapper
node_cli_inspect -->|"inspects PDF"| node_wrapper
node_cli_update -->|"updates PDF"| node_wrapper
node_cli_remove -->|"removes content"| node_wrapper
node_wrapper -->|"builds fields"| node_field_models
node_field_models -->|"renders widgets"| node_watermark
node_wrapper -->|"draws elements"| node_raw_elements
node_wrapper -->|"adds annotations"| node_annotations
node_wrapper -->|"merges PDFs"| node_pdfarray
node_pdfarray -->|"extracts pages"| node_pdf_docs

click node_wrapper "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/wrapper.py"
click node_pdfarray "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/types.py"
click node_cli_entry "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/entry.py"
click node_cli_create "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/create.py"
click node_cli_inspect "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/inspect.py"
click node_cli_update "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/update.py"
click node_cli_remove "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/remove.py"
click node_field_models "https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/widgets"
click node_field_middleware "https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/middleware"
click node_hooks "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/hooks.py"
click node_raw_elements "https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/raw"
click node_annotations "https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/annotations"
click node_watermark "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/watermark.py"
click node_pdf_docs "https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/types.py"

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_wrapper,node_pdfarray,node_operator toneBlue
class node_cli_entry,node_cli_create,node_cli_inspect,node_cli_update,node_cli_remove toneAmber
class node_field_models,node_field_middleware,node_hooks toneMint
class node_raw_elements,node_annotations,node_watermark toneRose
class node_pdf_docs,node_developer,node_input_pdf,node_output_pdf toneIndigo
```

## Components

### Python API

- [PdfWrapper](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/wrapper.py): `PyPDFForm/lib/wrapper.py`
- [PDF collections](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/types.py): `PyPDFForm/lib/types.py`

### Command Line

- [CLI entry](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/entry.py): `PyPDFForm/cli/entry.py`
- [Create commands](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/create.py): `PyPDFForm/cli/create.py`
- [Inspect commands](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/inspect.py): `PyPDFForm/cli/inspect.py`
- [Update commands](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/update.py): `PyPDFForm/cli/update.py`
- [Remove commands](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/cli/remove.py): `PyPDFForm/cli/remove.py`

### Form Fields

- [Field models](https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/widgets): `PyPDFForm/lib/widgets`
- [Field middleware](https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/middleware): `PyPDFForm/lib/middleware`
- [Field hooks](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/hooks.py): `PyPDFForm/lib/hooks.py`

### PDF Content

- [Raw elements](https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/raw): `PyPDFForm/lib/raw`
- [Annotations](https://github.com/chinapandaman/pypdfform/tree/master/PyPDFForm/lib/annotations): `PyPDFForm/lib/annotations`
- [Watermark drawing](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/watermark.py): `PyPDFForm/lib/watermark.py`

### Document Operations

- [PDF operations](https://github.com/chinapandaman/pypdfform/blob/master/PyPDFForm/lib/types.py): `PyPDFForm/lib/types.py`

### Other components

- **Python developer**
- **CLI user**
- **Input PDF**
- **Output PDF**

## Connections

- Python developer → PdfWrapper: calls API
- Input PDF → PdfWrapper: loads PDF
- PdfWrapper → Output PDF: writes PDF
- PdfWrapper → Field middleware: loads fields
- Field middleware → PdfWrapper: exposes state
- PdfWrapper → Field hooks: triggers hooks
- CLI user → CLI entry: runs commands
- CLI entry → Create commands: dispatches
- CLI entry → Inspect commands: dispatches
- CLI entry → Update commands: dispatches
- CLI entry → Remove commands: dispatches
- Create commands → PdfWrapper: creates content
- Inspect commands → PdfWrapper: inspects PDF
- Update commands → PdfWrapper: updates PDF
- Remove commands → PdfWrapper: removes content
- PdfWrapper → Field models: builds fields
- Field models → Watermark drawing: renders widgets
- PdfWrapper → Raw elements: draws elements
- PdfWrapper → Annotations: adds annotations
- PdfWrapper → PDF collections: merges PDFs
- PDF collections → PDF operations: extracts pages