# m1ck4/pdfmd architecture

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

- Interactive diagram: https://gitdiagram.com/m1ck4/pdfmd
- Repository: https://github.com/m1ck4/pdfmd

## Overview

pdfmd is a local PDF-to-Markdown converter with CLI and desktop interfaces. Both initiate conversion through the shared pipeline: PDF text is extracted (native or OCR), represented in a page model, cleaned and annotated, then rendered to Markdown; optional image export writes assets alongside the result. The README also documents batch conversion, password-protected PDFs, table reconstruction, math preservation, and GUI profiles. The source index confirms several module references; OCR-tool wiring and some pipeline details are not fully shown, so optional integration edges are marked unverified.

Main entry points: [`pdfmd/pipeline.py`](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/pipeline.py) (Conversion pipeline), [`pdfmd/transform.py`](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/transform.py) (Text cleanup), [`pdfmd/extract.py`](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/extract.py) (OCR engines), [`pdfmd/app_gui.py`](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/app_gui.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gui["Desktop GUI<br/>[app_gui.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_conversion["Conversion engine"]
  node_pipeline["Conversion pipeline<br/>[pipeline.py]"]
  node_extract["PDF extraction<br/>[extract.py]"]
  node_models["Page model<br/>[models.py]"]
  node_ocr["OCR engines<br/>[extract.py]"]
end

subgraph group_content["Content processing"]
  node_transform["Text cleanup<br/>[transform.py]"]
  node_tables["Table detection<br/>[tables.py]"]
  node_equations["Math normalization<br/>[equations.py]"]
  node_render["Markdown rendering<br/>[render.py]"]
end

subgraph group_outputs["Output"]
  node_markdown["Markdown file"]
  node_images["Exported images"]
end

node_user(("User"))
node_tesseract["Tesseract"]
node_ocrmypdf["OCRmyPDF"]

node_user -->|"uses"| node_gui
node_user -->|"invokes"| node_cli
node_gui -->|"runs conversion"| node_pipeline
node_cli -->|"runs conversion"| node_pipeline
node_pipeline -->|"extracts pages"| node_extract
node_extract -->|"builds pages"| node_models
node_pipeline -->|"transforms pages"| node_transform
node_pipeline -->|"renders Markdown"| node_render
node_transform -->|"detects tables"| node_tables
node_transform -->|"normalizes math"| node_equations
node_render -->|"uses annotations"| node_transform
node_pipeline -->|"writes output"| node_markdown
node_pipeline -->|"exports assets"| node_images
node_ocr -.->|"may invoke"| node_tesseract
node_ocr -.->|"may invoke"| node_ocrmypdf

click node_gui "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/app_gui.py"
click node_cli "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/cli.py"
click node_pipeline "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/pipeline.py"
click node_extract "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/extract.py"
click node_models "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/models.py"
click node_ocr "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/extract.py"
click node_transform "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/transform.py"
click node_tables "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/tables.py"
click node_equations "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/equations.py"
click node_render "https://github.com/m1ck4/pdfmd/blob/main/pdfmd/render.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_gui,node_cli,node_user toneBlue
class node_pipeline,node_extract,node_models,node_ocr toneAmber
class node_transform,node_tables,node_equations,node_render toneMint
class node_markdown,node_images toneRose
class node_tesseract,node_ocrmypdf toneIndigo
```

## Components

### User interfaces

- [Desktop GUI](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/app_gui.py): `pdfmd/app_gui.py`
- [Command line](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/cli.py): `pdfmd/cli.py`

### Conversion engine

- [Conversion pipeline](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/pipeline.py): `pdfmd/pipeline.py`
- [PDF extraction](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/extract.py): `pdfmd/extract.py`
- [Page model](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/models.py): `pdfmd/models.py`
- [OCR engines](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/extract.py): `pdfmd/extract.py`

### Content processing

- [Text cleanup](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/transform.py): `pdfmd/transform.py`
- [Table detection](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/tables.py): `pdfmd/tables.py`
- [Math normalization](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/equations.py): `pdfmd/equations.py`
- [Markdown rendering](https://github.com/m1ck4/pdfmd/blob/main/pdfmd/render.py): `pdfmd/render.py`

### Output

- **Markdown file**
- **Exported images**

### Other components

- **User**
- **Tesseract**
- **OCRmyPDF**

## Connections

- User → Desktop GUI: uses (evidence: `README.md`)
- User → Command line: invokes (evidence: `README.md`)
- Desktop GUI → Conversion pipeline: runs conversion (evidence: `pdfmd/app_gui.py`)
- Command line → Conversion pipeline: runs conversion (evidence: `pdfmd/cli.py`)
- Conversion pipeline → PDF extraction: extracts pages (evidence: `pdfmd/pipeline.py`)
- PDF extraction → Page model: builds pages (evidence: `pdfmd/models.py`)
- Conversion pipeline → Text cleanup: transforms pages (evidence: `pdfmd/pipeline.py`)
- Conversion pipeline → Markdown rendering: renders Markdown (evidence: `pdfmd/pipeline.py`)
- Text cleanup → Table detection: detects tables (evidence: `pdfmd/transform.py`)
- Text cleanup → Math normalization: normalizes math (evidence: `pdfmd/transform.py`)
- Markdown rendering → Text cleanup: uses annotations (evidence: `pdfmd/render.py`)
- Conversion pipeline → Markdown file: writes output (evidence: `pdfmd/pipeline.py`)
- Conversion pipeline → Exported images: exports assets (evidence: `pdfmd/pipeline.py`)
- OCR engines → Tesseract: may invoke (evidence: `README.md`)
- OCR engines → OCRmyPDF: may invoke (evidence: `README.md`)
