# ds4sd/docling architecture

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

- Interactive diagram: https://gitdiagram.com/ds4sd/docling
- Repository: https://github.com/ds4sd/docling

## Overview

##### Project Type and Purpose
- Docling is a document processing and conversion library. Its primary purpose is to parse diverse document formats (PDF, DOCX, HTML, XLSX, images, etc.) and output a unified representation (the DoclingDocument) with various export formats (Markdown, HTML, JSON).
- It provides a simple CLI interface as well as a Python API and integrates with external AI tools (e.g., LangChain, LlamaIndex) for advanced processing. The README and file structure make it clear that Docling is both a conversion tool and a backend library that supports various pipelines and backends.

##### Analyzing the File Structure
- Top-level directories and files:
- .github: Contains templates, workflows, and CI/CD configurations.
- docling/: This is the core package. It is structured into multiple subdirectories:
- backend: Contains modules for handling various document formats (HTML, Markdown, PDF, DOCX, XML, etc.). Notice separate subdirectories for JSON and XML backends.
- cli: Implements the command-line interface and user interaction (main entry-point with main.py).
- datamodel: Houses the unified document models and pipeline settings.
- models: Contains specialized models such as OCR, layout analysis, and classification models.
- pipeline: Contains implementations of processing pipelines (e.g., standard_pdf_pipeline, simple_pipeline) that orchestrate the conversion routines.
- chunking, utils, and exception handling: Provide supporting functionality.
- tests/: Contains extensive tests including data, integration tests, and use-case validations, ensuring that every aspect of document conversion is verified.
- Other project files (e.g., Dockerfile, pyproject.toml) indicate packaging, containerization, and dependency management details.

a. Main components:
- User Interface Layer: Consists of the CLI in docling/cli and any external API consumers.
- Document Converter: The DocumentConverter module (document_converter.py) that acts as the main entry point to process documents.
- Pipeline Core: Represents the processing pipelines (simple_pipeline, standard_pdf_pipeline) that orchestrate the conversion flow.
- Backend Modules: A set of backend adapters (e.g., asciidoc_backend, html_backend, json backends, pdf_backend) that handle format-specific parsing.
- Datamodel: The unified DoclingDocument and associated classes in the datamodel directory.
- Models: Specialized processing models (OCR, layout, classification) located in the models directory.
- Utilities & Helpers: Commons utility functions in the utils folder that support tasks such as OCR, visualization, and model downloading.
- Testing & CI/CD: Although not part of runtime architecture, the tests along with GitHub workflows indicate continuous validation and deployment pipelines which can be illustrated as supporting infrastructure.

b. Relationships and Interactions:
- The User interacts via the CLI or a programmatic API.
- The CLI passes inputs to the DocumentConverter.
- The DocumentConverter orchestrates tasks by invoking the appropriate pipeline.
- The pipeline coordinates calls to various backend services/adapters based on the document format (the backends are interchangeable, modular components).
- The backends process input and convert them into a unified document structure defined in the datamodel.
- The Models might optionally be invoked within the backends or pipelines to provide advanced analyses (like OCR or layout processing).
- Utility modules support processing workflows and integrate with external services when advanced processing (like AI integrations) is needed.

c. Architectural Patterns and Design Principles:
- Modular & Extensible Architecture: Each document format is handled by a dedicated backend module, making it easy to add support for new formats.
- Pipeline Design: The conversion process is designed as a pipeline where each stage performs specific tasks – this is seen in the pipeline components.
- Separation of Concerns: Distinct layers for CLI, conversion orchestration, backend formatting, and data modeling.
- Plug-and-Play Integration: The design allows for external model integrations (like AI-based text extraction and OCR), which are managed through specialized model modules.

d. Relevant Technologies, Frameworks, and Libraries:
- Python as the main programming language, managed with Poetry.
- GitHub Actions for CI/CD (as seen in the workflows folder).
- Docker for containerization.
- Pre-commit, isort, Black, and other tooling for code quality.
- The documentation references external libraries (e.g., external AI services like LangChain) that interact with Docling.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Interface"]:::external
    end

    %% Core Conversion Engine
    subgraph "Core Conversion Engine"
        DC["Document Converter"]:::service
        
        %% Processing Pipeline Subgraph
        subgraph "Processing Pipeline"
            BP["Base Pipeline"]:::pipeline
            SP["Simple Pipeline"]:::pipeline
            SPP["Standard PDF Pipeline"]:::pipeline
        end
        
        %% Backend Modules Subgraph
        subgraph "Backend Modules"
            BM["General Backends"]:::backend
            HB["HTML Backend"]:::backend
            JB["JSON Backend"]:::backend
            PB["PDF Backend"]:::backend
        end
        
        %% Unified Document Datamodel Subgraph
        subgraph "Unified Document Datamodel"
            UD["Document Model"]:::datamodel
        end
        
        %% Advanced Models & AI Integrations Subgraph
        subgraph "Advanced Models & AI Integrations"
            OM["OCR Model"]:::model
            LM["Layout Analysis"]:::model
        end
        
        %% Utilities & Helpers Node
        UTI["Utilities & Helpers"]:::utility
    end

    %% Supporting Infrastructure: Testing & CI/CD
    subgraph "Testing & CI/CD"
        TEST["Tests"]:::ci
        CICD["CI/CD Workflows"]:::ci
    end

    %% Data Flow
    CLI -->|"triggers"| DC
    DC -->|"invokes"| BP
    DC -->|"invokes"| SP
    DC -->|"invokes"| SPP
    BP -->|"processes documents"| BM
    SP -->|"processes documents"| BM
    SPP -->|"processes documents"| BM
    BM -->|"outputs unified doc"| UD
    BM -->|"optional analysis"| OM
    BM -->|"optional analysis"| LM
    UTI ---|"supports"| DC
    UTI ---|"supports"| BP
    UTI ---|"supports"| SP
    UTI ---|"supports"| SPP

    %% Legend (Explanation of Colors)
    LEGEND1["Service/Module"]:::service
    LEGEND2["Pipeline Component"]:::pipeline
    LEGEND3["Backend Adapter"]:::backend
    LEGEND4["Datamodel"]:::datamodel
    LEGEND5["Advanced Model/AI"]:::model
    LEGEND6["Utility/Helper"]:::utility
    LEGEND7["CI/CD & Testing"]:::ci

    %% Click Events
    click CLI "https://github.com/ds4sd/docling/blob/main/docling/cli/main.py"
    click DC "https://github.com/ds4sd/docling/blob/main/docling/document_converter.py"
    click BP "https://github.com/ds4sd/docling/blob/main/docling/pipeline/base_pipeline.py"
    click SP "https://github.com/ds4sd/docling/blob/main/docling/pipeline/simple_pipeline.py"
    click SPP "https://github.com/ds4sd/docling/blob/main/docling/pipeline/standard_pdf_pipeline.py"
    click BM "https://github.com/ds4sd/docling/tree/main/docling/backend/"
    click HB "https://github.com/ds4sd/docling/blob/main/docling/backend/html_backend.py"
    click JB "https://github.com/ds4sd/docling/blob/main/docling/backend/json/docling_json_backend.py"
    click PB "https://github.com/ds4sd/docling/blob/main/docling/backend/pdf_backend.py"
    click UD "https://github.com/ds4sd/docling/blob/main/docling/datamodel/document.py"
    click OM "https://github.com/ds4sd/docling/blob/main/docling/models/easyocr_model.py"
    click LM "https://github.com/ds4sd/docling/blob/main/docling/models/layout_model.py"
    click UTI "https://github.com/ds4sd/docling/blob/main/docling/utils/utils.py"
    click TEST "https://github.com/ds4sd/docling/tree/main/tests/"
    click CICD "https://github.com/ds4sd/docling/tree/main/.github/workflows/"

    %% Class Definitions with Colors
    classDef external fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef pipeline fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef backend fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef datamodel fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef model fill:#FCF3CF,stroke:#B9770E,stroke-width:2px;
    classDef utility fill:#E8F8F5,stroke:#117864,stroke-width:2px;
    classDef ci fill:#FDEBD0,stroke:#D68910,stroke-width:2px;
```
