# artifexsoftware/pdf2docx architecture

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

- Interactive diagram: https://gitdiagram.com/artifexsoftware/pdf2docx
- Repository: https://github.com/artifexsoftware/pdf2docx

## Overview

##### Project Type and Purpose
- This is an open-source conversion tool/library (pdf2docx) that parses PDF files and re-creates their layout and contents in DOCX format.
- It provides:
- A Python API (core library)
- A Command-Line Interface (main.py)
- A GUI application (App.py / MainFrame.py)
- Multiprocessing support for page parsing
- Integration with external libraries: PyMuPDF (PDF extraction) and python-docx (DOCX generation)

##### File Structure Analysis
- Top-level directories:
- pdf2docx/        ← core package
- docs/            ← documentation sources
- test/            ← test suite & sample files
- Under pdf2docx/:
- common/          ← shared classes (Block, Element, Collection, algorithm, constants, docx helper)
- font/            ← font handling
- gui/             ← GUI components (App, MainFrame)
- image/           ← image extraction & block/span representation
- layout/          ← layout analysis (Sections, Columns, Blocks)
- page/            ← low-level PDF page extraction, raw page factories
- table/           ← table structure, cell/row management, border/shading
- text/            ← text spans, lines, blocks
- converter.py     ← orchestrates parse→layout→generate pipeline
- main.py          ← CLI entry point
- Configuration & metadata:
- setup.py, requirements.txt, version.txt
- CI workflows (GitHub Actions), licensing

##### Key Points from README
- Three-stage pipeline: Extract → Parse Layout → Generate DOCX
- Uses PyMuPDF to pull raw PDF objects, then rule-based parsing into semantic blocks, then python-docx to write docx
- Supports multiprocessing per page

a. Main Components
1. Input Layer
- PDF File (user input)
- CLI or GUI invoking the pipeline
2. Extraction Layer
- PyMuPDF Library
- page.RawPageFitz / RawPage factories
3. Parsing Layer (Core Modules)
- page → yields RawPage objects
- common / algorithm: utility functions
- layout: Sections, Columns, Blocks
- text: Char, Span, Line, TextBlock
- image: ImageExtractor, ImageBlock, ImageSpan
- table: TableStructure, Rows, Cells, TablesConstructor
- font: Fonts class mapping styles
4. Coordination Layer
- converter.py: orchestrates multiprocessing, feeds pages into parsing pipeline
5. Generation Layer
- python-docx integration (common/docx.py helper)
- building DOCX Document object
6. Output Layer
- DOCX File (user output)
7. Interfaces
- CLI (main.py)
- GUI (App.py / MainFrame.py)
b. Relationships & Data Flow
- converter.py → dispatch to worker processes → RawPageFactory → RawPageFitz uses PyMuPDF
- Domain modules produce intermediate object graph (Blocks, Spans, Structures)
- object graph → python-docx helper → Document.write → DOCX file
c. Architectural Patterns & Principles
- Pipeline pattern: extraction → parsing → generation
- Modular package structure by concern (Separation of Concerns)
- Multiprocessing for page-level parallelism
- Adapter pattern: Wrapping PyMuPDF and python-docx interfaces into uniform data structures
d. Key Technologies & Libraries
- PyMuPDF (fitz) for PDF extraction
- python-docx for DOCX creation
- multiprocessing module for parallel page parsing
- click or argparse in main.py for CLI (depending on implementation)

##### Essential Elements
- converter.py as the orchestrator
- CLI (main.py) and GUI (App/MainFrame) entry points
- External dependencies: PyMuPDF and python-docx
- Input/output artifacts (PDF, DOCX)
- Multiprocessing component boundary

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input and Interfaces
    PDF["PDF File"]:::external
    subgraph "Interface Layer"
        direction TB
        CLI["CLI Interface"]:::interface
        GUIApp["GUI App (App.py)"]:::interface
        GUIMain["GUI MainFrame"]:::interface
    end

    %% Coordination and Multiprocessing
    subgraph "Coordination Layer"
        direction TB
        Converter["converter.py"]:::coordination
    end

    %% Extraction Layer
    subgraph "Extraction Layer"
        direction TB
        RawFactory["RawPageFactory"]:::extraction
        RawFitz["RawPageFitz"]:::extraction
        RawPage["RawPage"]:::extraction
        BasePage["BasePage"]:::extraction
        Pages["Pages"]:::extraction
        PyMuPDF["PyMuPDF"]:::external
    end

    %% Parsing Layer
    subgraph "Parsing Layer"
        direction TB
        subgraph "Core Utilities"
            Algorithm["algorithm.py"]:::parsing
            Constants["constants.py"]:::parsing
            BlockCls["Block.py"]:::parsing
            CollectionCls["Collection.py"]:::parsing
            ElementCls["Element.py"]:::parsing
        end
        DOCXHelper["docx.py"]:::parsing
        subgraph "Layout Module"
            Layout["Layout.py"]:::parsing
            Section["Section.py"]:::parsing
            Sections["Sections.py"]:::parsing
            Column["Column.py"]:::parsing
            BlocksMod["Blocks.py"]:::parsing
        end
        subgraph "Text Module"
            Char["Char.py"]:::parsing
            TextSpan["TextSpan.py"]:::parsing
            Spans["Spans.py"]:::parsing
            Line["Line.py"]:::parsing
            Lines["Lines.py"]:::parsing
            TextBlock["TextBlock.py"]:::parsing
        end
        subgraph "Image Module"
            ImgExtractor["ImagesExtractor.py"]:::parsing
            ImageMod["Image.py"]:::parsing
            ImgSpan["ImageSpan.py"]:::parsing
            ImgBlock["ImageBlock.py"]:::parsing
        end
        subgraph "Table Module"
            TableStruct["TableStructure.py"]:::parsing
            TablesCtor["TablesConstructor.py"]:::parsing
            Border["Border.py"]:::parsing
            Cell["Cell.py"]:::parsing
            Cells["Cells.py"]:::parsing
            Row["Row.py"]:::parsing
            Rows["Rows.py"]:::parsing
            TableBlock["TableBlock.py"]:::parsing
        end
        FontsMod["Fonts.py"]:::parsing
        subgraph "Shape Module"
            PathMod["Path.py"]:::parsing
            PathsMod["Paths.py"]:::parsing
            ShapeMod["Shape.py"]:::parsing
            ShapesMod["Shapes.py"]:::parsing
        end
    end

    %% Generation Layer
    subgraph "Generation Layer"
        direction TB
        DocxGen["python-docx"]:::external
        DocxHelper["docx.py"]:::generation
    end

    %% Output
    DOCX["DOCX File"]:::external

    %% Connections
    PDF --> CLI
    PDF --> GUIApp
    GUIApp --> GUIMain
    CLI --> Converter
    GUIMain --> Converter
    Converter -->|dispatch RawPageFactory| RawFactory
    RawFactory --> RawFitz
    RawFitz --> RawPage
    RawPage --> BasePage
    BasePage --> Pages
    RawPage --> Algorithm
    RawPage --> Layout
    RawPage --> Char
    RawPage --> ImgExtractor
    RawPage --> TableStruct
    RawPage --> FontsMod
    RawPage --> PathMod
    Algorithm --> Layout
    Algorithm --> Char
    Algorithm --> ImgExtractor
    Algorithm --> TableStruct
    Algorithm --> FontsMod
    Algorithm --> PathMod
    Layout --> DOCXHelper
    Char --> DOCXHelper
    ImgExtractor --> DOCXHelper
    TableStruct --> DOCXHelper
    FontsMod --> DOCXHelper
    PathMod --> DOCXHelper
    DOCXHelper --> DocxGen
    DocxGen --> DOCX

    %% Click Events
    click CLI "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/main.py"
    click GUIApp "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/gui/App.py"
    click GUIMain "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/gui/MainFrame.py"
    click Converter "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/converter.py"
    click RawFactory "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/page/RawPageFactory.py"
    click RawFitz "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/page/RawPageFitz.py"
    click RawPage "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/page/RawPage.py"
    click BasePage "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/page/BasePage.py"
    click Pages "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/page/Pages.py"
    click Algorithm "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/algorithm.py"
    click Constants "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/constants.py"
    click BlockCls "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/Block.py"
    click CollectionCls "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/Collection.py"
    click ElementCls "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/Element.py"
    click DOCXHelper "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/common/docx.py"
    click Layout "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/layout/Layout.py"
    click Section "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/layout/Section.py"
    click Sections "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/layout/Sections.py"
    click Column "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/layout/Column.py"
    click BlocksMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/layout/Blocks.py"
    click Char "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/Char.py"
    click TextSpan "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/TextSpan.py"
    click Spans "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/Spans.py"
    click Line "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/Line.py"
    click Lines "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/Lines.py"
    click TextBlock "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/text/TextBlock.py"
    click ImgExtractor "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/image/ImagesExtractor.py"
    click ImageMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/image/Image.py"
    click ImgSpan "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/image/ImageSpan.py"
    click ImgBlock "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/image/ImageBlock.py"
    click TableStruct "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/TableStructure.py"
    click TablesCtor "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/TablesConstructor.py"
    click Border "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/Border.py"
    click Cell "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/Cell.py"
    click Cells "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/Cells.py"
    click Row "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/Row.py"
    click Rows "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/Rows.py"
    click TableBlock "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/table/TableBlock.py"
    click FontsMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/font/Fonts.py"
    click PathMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/shape/Path.py"
    click PathsMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/shape/Paths.py"
    click ShapeMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/shape/Shape.py"
    click ShapesMod "https://github.com/artifexsoftware/pdf2docx/blob/master/pdf2docx/shape/Shapes.py"

    %% Styles
    classDef interface fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef extraction fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef parsing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef generation fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef coordination fill:#E6E6FA,stroke:#333,stroke-width:1px
```
