# mathinml/pdf2md architecture

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

- Interactive diagram: https://gitdiagram.com/mathinml/pdf2md
- Repository: https://github.com/mathinml/pdf2md

## Overview

##### File structure
- Top-level scripts:
- cli.py       – argument parsing
- main.py      – orchestration of modules
- processor.py – PDFMarkdownProcessor, coordinates converters and I/O
- converters.py– two converter classes:
· PDFToImageConverter (uses pdf2image + poppler-utils)
· ImageToMarkdownConverter (wraps modelscope inference)
- requirements.txt lists Python dependencies; external dependency on poppler-utils or homebrew poppler.
- test_ocr.pdf is a sample input; output.md is the target.

##### README for additional insights
- Installation steps for poppler (Ubuntu/macOS)
- Model download instructions (modelscope CLI)
- Usage: `python main.py --pdf ... --model ... --output ...`

##### Components
a. User / CLI interface
b. Argument parser (cli.py)
c. Main orchestrator (main.py + PDFMarkdownProcessor)
d. PDF-to-Image converter (pdf2image + poppler-utils)
e. Image-to-Markdown converter (modelscope + Qwen model)
f. File system (input PDF, output Markdown, local model files)
g. External dependencies (poppler-utils, Python libs, modelscope service or local model)

##### Relationships and interactions
- The User issues a command → CLI Parser
- CLI Parser passes arguments to Main
- Main uses PDFMarkdownProcessor to:
1. Invoke PDFToImageConverter → generates images in memory or temp files
2. For each image → call ImageToMarkdownConverter → returns text blocks
3. Aggregate text → produce final Markdown
- Final Markdown is written to disk
- Converters rely on external binaries (poppler-utils) and model artifacts

##### Architectural patterns and design principles
- Modular monolith: each conversion step is encapsulated in its own class
- Single responsibility: parsing, processing, conversion, and I/O each live in separate modules
- Pipeline pattern: sequential processing stages (PDF → Image → Markdown)
- Dependency inversion for converters: abstract converter interfaces could allow swapping out engines

##### Technologies, frameworks, libraries
- Python 3.x
- pdf2image + poppler-utils (Ubuntu/Debian or Homebrew)
- modelscope SDK + Qwen/VL model for vision‐language inference
- Standard library for CLI (argparse), file I/O

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    User["User"]:::external
    CLI["CLI Parser"]:::custom
    Main["Main Orchestrator"]:::custom
    Processor["PDFMarkdownProcessor"]:::custom
    subgraph Converters
        PIC["PDFToImageConverter"]:::custom
        IMC["ImageToMarkdownConverter"]:::custom
    end
    POPPLER["poppler-utils"]:::external
    MODELSVC["Modelscope Service"]:::service
    subgraph Filesystem
        InputPDF[(PDF File\ntest_ocr.pdf)]:::storage
        ModelArtifacts[(Local Model\nFiles)]:::storage
        OutputMD[(Output Markdown\noutput.md)]:::storage
        Requirements["requirements.txt"]:::storage
        README["README.md"]:::storage
    end

    %% Flow
    User -->|"runs CLI"| CLI
    CLI -->|"parses args"| Main
    Main -->|"orchestrates"| Processor
    Main -->|"reads"| InputPDF
    Main -->|"loads model"| ModelArtifacts

    Processor -->|"step1: convert PDF→images"| PIC
    PIC -->|"images"| IMC
    IMC -->|"text blocks"| Processor
    Processor -->|"writes"| OutputMD

    PIC -.->|"uses binary"| POPPLER
    IMC -.->|"calls inference"| MODELSVC

    %% Click events
    click CLI "https://github.com/mathinml/pdf2md/blob/main/cli.py"
    click Main "https://github.com/mathinml/pdf2md/blob/main/main.py"
    click Processor "https://github.com/mathinml/pdf2md/blob/main/processor.py"
    click PIC "https://github.com/mathinml/pdf2md/blob/main/converters.py"
    click IMC "https://github.com/mathinml/pdf2md/blob/main/converters.py"
    click Requirements "https://github.com/mathinml/pdf2md/blob/main/requirements.txt"
    click README "https://github.com/mathinml/pdf2md/blob/main/README.md"
    click InputPDF "https://github.com/mathinml/pdf2md/blob/main/test_ocr.pdf"

    %% Styles
    classDef custom fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef external fill:#c6d8ff,stroke:#333,stroke-width:1px
    classDef service fill:#e0c6ff,stroke:#333,stroke-width:1px
    classDef storage fill:#fff3a6,stroke:#333,stroke-width:1px,font-style:italic
```
