# opendataloader-project/opendataloader-pdf architecture

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

- Interactive diagram: https://gitdiagram.com/opendataloader-project/opendataloader-pdf
- Repository: https://github.com/opendataloader-project/opendataloader-pdf

## Overview

OpenDataLoader PDF converts PDFs into structured, layout-aware outputs and can auto-tag PDFs for accessibility. Users invoke a Python, Node.js, Java API, CLI, or MCP tool; conversion is handled by the Java core, with optional hybrid processing for complex pages, then emitted in formats such as Markdown, JSON, HTML, and Tagged PDF. The README establishes these product workflows and capabilities; sampled source confirms selected CLI, Node-to-JVM, and hybrid HTTP behavior, but not the internal processor call sequence.

Main entry points: [`java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java) (Document Processing), [`java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java) (Java CLI), [`java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java) (Java API), [`java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java) (Hybrid Routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_python["Python SDK<br/>[runner.py]"]
  node_node["Node SDK<br/>[index.ts]"]
  node_java_cli["Java CLI<br/>[CLIMain.java]"]
  node_mcp["MCP Server<br/>[server.py]"]
end

subgraph group_core["PDF Processing"]
  node_api["Java API"]
  node_config["Conversion Config<br/>[Config.java]"]
  node_document["Document Processing"]
  node_reading_order["Reading Order"]
  node_lists["List Detection<br/>[ListProcessor.java]"]
  node_paragraphs["Paragraph Analysis"]
  node_sanitizer["Safety Filters"]
end

subgraph group_hybrid["Hybrid Analysis"]
  node_hybrid_processor["Hybrid Routing"]
  node_triage["Page Triage"]
  node_hybrid_client["Hybrid Client<br/>[HybridClient.java]"]
  node_docling_client["Docling Client"]
  node_backend["Hybrid Backend"]
end

subgraph group_outputs["Outputs and Accessibility"]
  node_markdown["Markdown Output"]
  node_json["JSON Output<br/>[JsonWriter.java]"]
  node_html["HTML Output<br/>[HtmlGenerator.java]"]
  node_tagging["Auto-tagging"]
  node_tagged_pdf["Tagged PDF<br/>[PDFWriter.java]"]
end

node_user(("PDF User"))

node_user -->|"calls"| node_python
node_user -->|"calls"| node_node
node_user -->|"runs"| node_java_cli
node_user -->|"requests conversion"| node_mcp
node_node -->|"spawns JVM CLI"| node_java_cli
node_java_cli -->|"invokes"| node_api
node_api -.->|"processes PDF"| node_document
node_document -.->|"orders content"| node_reading_order
node_document -.->|"detects lists"| node_lists
node_document -.->|"analyzes paragraphs"| node_paragraphs
node_document -.->|"filters content"| node_sanitizer
node_document -.->|"generates"| node_markdown
node_document -.->|"generates"| node_json
node_document -.->|"generates"| node_html
node_document -.->|"auto-tags"| node_tagging
node_tagging -.->|"writes"| node_tagged_pdf
node_hybrid_processor -.->|"triages pages"| node_triage
node_hybrid_processor -.->|"requests analysis"| node_hybrid_client
node_hybrid_client -.->|"uses client"| node_docling_client
node_docling_client -->|"sends HTTP request"| node_backend
node_mcp -->|"calls conversion"| node_python
node_config -.->|"configures"| node_api

click node_python "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf/src/opendataloader_pdf/runner.py"
click node_node "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/node/opendataloader-pdf/src/index.ts"
click node_java_cli "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java"
click node_mcp "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py"
click node_api "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java"
click node_config "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/Config.java"
click node_document "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java"
click node_reading_order "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/readingorder/XYCutPlusPlusSorter.java"
click node_lists "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ListProcessor.java"
click node_paragraphs "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ParagraphProcessor.java"
click node_sanitizer "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/utils/ContentSanitizer.java"
click node_hybrid_processor "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java"
click node_triage "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/TriageProcessor.java"
click node_hybrid_client "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridClient.java"
click node_docling_client "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java"
click node_markdown "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/markdown/MarkdownGenerator.java"
click node_json "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/json/JsonWriter.java"
click node_html "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/html/HtmlGenerator.java"
click node_tagging "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/AutoTaggingProcessor.java"
click node_tagged_pdf "https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/pdf/PDFWriter.java"

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_python,node_node,node_java_cli,node_mcp,node_user toneBlue
class node_api,node_config,node_document,node_reading_order,node_lists,node_paragraphs,node_sanitizer toneAmber
class node_hybrid_processor,node_triage,node_hybrid_client,node_docling_client,node_backend toneMint
class node_markdown,node_json,node_html,node_tagging,node_tagged_pdf toneRose
```

## Components

### User Interfaces

- [Python SDK](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf/src/opendataloader_pdf/runner.py): `python/opendataloader-pdf/src/opendataloader_pdf/runner.py`
- [Node SDK](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/node/opendataloader-pdf/src/index.ts): `node/opendataloader-pdf/src/index.ts`
- [Java CLI](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java): `java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java`
- [MCP Server](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py): `python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py`

### PDF Processing

- [Java API](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java`
- [Conversion Config](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/Config.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/Config.java`
- [Document Processing](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`
- [Reading Order](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/readingorder/XYCutPlusPlusSorter.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/readingorder/XYCutPlusPlusSorter.java`
- [List Detection](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ListProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ListProcessor.java`
- [Paragraph Analysis](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ParagraphProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/ParagraphProcessor.java`
- [Safety Filters](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/utils/ContentSanitizer.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/utils/ContentSanitizer.java`

### Hybrid Analysis

- [Hybrid Routing](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java`
- [Page Triage](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/TriageProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/TriageProcessor.java`
- [Hybrid Client](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridClient.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridClient.java`
- [Docling Client](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java`
- **Hybrid Backend**

### Outputs and Accessibility

- [Markdown Output](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/markdown/MarkdownGenerator.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/markdown/MarkdownGenerator.java`
- [JSON Output](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/json/JsonWriter.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/json/JsonWriter.java`
- [HTML Output](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/html/HtmlGenerator.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/html/HtmlGenerator.java`
- [Auto-tagging](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/AutoTaggingProcessor.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/AutoTaggingProcessor.java`
- [Tagged PDF](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/pdf/PDFWriter.java): `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/pdf/PDFWriter.java`

### Other components

- **PDF User**

## Connections

- PDF User → Python SDK: calls (evidence: `README.md`)
- PDF User → Node SDK: calls (evidence: `README.md`)
- PDF User → Java CLI: runs (evidence: `README.md`)
- PDF User → MCP Server: requests conversion (evidence: `python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py`)
- Node SDK → Java CLI: spawns JVM CLI (evidence: `node/opendataloader-pdf/src/index.ts`)
- Java CLI → Java API: invokes (evidence: `java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java`)
- Java API → Document Processing: processes PDF (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java`)
- Document Processing → Reading Order: orders content (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → List Detection: detects lists (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → Paragraph Analysis: analyzes paragraphs (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → Safety Filters: filters content (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → Markdown Output: generates (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → JSON Output: generates (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → HTML Output: generates (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Document Processing → Auto-tagging: auto-tags (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/DocumentProcessor.java`)
- Auto-tagging → Tagged PDF: writes
- Hybrid Routing → Page Triage: triages pages
- Hybrid Routing → Hybrid Client: requests analysis
- Hybrid Client → Docling Client: uses client (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java`)
- Docling Client → Hybrid Backend: sends HTTP request (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java`)
- MCP Server → Python SDK: calls conversion (evidence: `python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py`)
- Conversion Config → Java API: configures (evidence: `java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/OpenDataLoaderPDF.java`)
