# rapidai/rapidocrpdf architecture

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

- Interactive diagram: https://gitdiagram.com/rapidai/rapidocrpdf
- Repository: https://github.com/rapidai/rapidocrpdf

## Overview

##### Project type and purpose
- This is an open-source Python library and CLI tool (“rapidocr_pdf”) whose purpose is to extract text from PDF files. It first tries direct text extraction via PyMuPDF and, if that fails (e.g., scanned or encrypted PDFs), falls back to an OCR engine (RapidOCR).

##### File structure
- Top-level:
- demo.py – example usage
- rapidocr_pdf/ – the core package
– main.py – exposes RapidOCRPDF class and CLI entry point
– utils/ – helper modules (logger.py, utils.py)
- docs/ – documentation
- tests/ – unit tests and sample PDF fixtures
- setup.py, requirements.txt, cliff.toml – packaging & config
- Modules indicate a clear separation: entry point (CLI & library API), core processing logic, utility support, and external resources (test PDFs).

##### README for additional insights
PDF → “can extract directly?” → yes → PyMuPDF, no → RapidOCR → results
- Highlights parameters (dpi, force_ocr, page ranges) and outputs (page number, text, confidence).

##### Main components of the system (to include
a. Client Interfaces
- Library API (RapidOCRPDF class)
- CLI wrapper (argparse in main.py)
b. PDF Loader/Validator
- Accepts file path or bytes, validates input
c. Extraction Manager
- Decision node: direct vs. OCR extraction
d. Direct Extractor
- PyMuPDF (fitz) calls to pull embedded text
e. OCR Extractor
- RapidOCR engine invocation (GPU/CPU options via torch config)
f. Utilities
- Logging (logger.py)
- Common routines (utils.py) for page slicing, parameter parsing
g. Output Aggregator
- Normalizes and returns List[page, text, confidence]
h. External Dependencies
- PyMuPDF, RapidOCR, Torch, Python stdlib

##### Relationships and interactions
- Data flow:
Client → Loader → Manager → {Direct Extractor ↔ PyMuPDF, OCR Extractor ↔ RapidOCR} → Aggregator → Client
- Utilities are invoked by multiple components for logging and shared routines.
- CLI and library share the same underlying pipeline.

##### Architectural patterns and design principles
- Strategy pattern: extraction strategy selected at runtime (direct vs. OCR)
- Single responsibility: modules have well-defined roles (I/O, business logic, utilities)
- Dependency injection: ocr_params passed through initializer for flexibility
- Testability: core logic isolated from CLI, covered by unit tests

##### Relevant technologies/frameworks/libraries
- Python ≥3.6
- PyMuPDF (fitz) for direct text extraction
- RapidOCR (with optional torch acceleration)
- argparse (or click) for CLI parsing
- pytest for testing
- packaging via setuptools (setup.py)

##### Diagramming recommendations
- Use rectangular blocks for internal components (Loader, Manager, Extractors, Aggregator)
- Use parallelograms for I/O interfaces (PDF file, CLI, library API)
- Blue for internal modules
- Green for external libraries/services
- Orange for I/O boundaries

##### Essential elements
- Clear labels on every block (e.g., “Extraction Manager”)
- Decision diamond for the direct‐vs‐OCR choice
- A note or annotation about configurable ocr_params

## Diagram (Mermaid)

```mermaid
graph TD
    %% I/O Interfaces
    Demo["Demo Script"]:::io
    CLI["CLI Entry Point"]:::io
    API["Library API"]:::io

    %% Internal Components
    Loader["PDF Loader/Validator"]:::internal
    Manager{"Direct Extraction possible?"}:::internal
    DirectExt["Direct Extractor"]:::internal
    OCRExt["OCR Extractor"]:::internal
    Aggregator["Output Aggregator"]:::internal

    %% Shared Utilities
    subgraph "Shared Utilities"
        Logger["Logger"]:::util
        Utils["Common Routines"]:::util
    end

    %% External Dependencies
    PyMuPDF(("PyMuPDF")):::external
    RapidOCR(("RapidOCR Engine")):::external
    Torch(("Torch (optional GPU)")):::external
    Stdlib(("Python stdlib")):::external

    %% Packaging & Config
    subgraph "Packaging & Config"
        Setup["setup.py"]:::util
        Requirements["requirements.txt"]:::util
        Cliff["cliff.toml"]:::util
    end

    %% Test Suite
    subgraph "Tests & Sample PDFs"
        TestSuite["tests/test_main.py"]:::util
        DirectImagePDF["direct_and_image.pdf"]:::io
        DirectExtractPDF["direct_extract.pdf"]:::io
        ImagePDF["image.pdf"]:::io
    end

    %% Data Flow
    Demo -->|"PDF path/bytes"| Loader
    CLI -->|"PDF path/bytes & params"| Loader
    API -->|"PDF bytes & params"| Loader

    Loader -->|"validated input"| Manager
    Manager -->|yes| DirectExt
    Manager -->|no| OCRExt

    DirectExt -->|calls fitz| PyMuPDF
    DirectExt -->|uses routines| Utils
    OCRExt -->|invokes engine| RapidOCR
    OCRExt -->|optional accel| Torch
    OCRExt -->|uses routines| Utils

    Loader -->|logging events| Logger
    Manager -->|logging events| Logger
    DirectExt -->|logging events| Logger
    OCRExt -->|logging events| Logger
    Aggregator -->|logging events| Logger

    DirectExt --> Aggregator
    OCRExt --> Aggregator
    Aggregator -->|"results (page, text, confidence)"| API
    Aggregator -->|"results (page, text, confidence)"| CLI
    Aggregator -->|"results (page, text, confidence)"| Demo

    Loader --> Stdlib
    CLI --> Stdlib

    %% Tests relationships
    TestSuite -->|tests| Loader
    TestSuite -->|tests| Manager
    TestSuite -->|uses sample PDF| DirectImagePDF
    TestSuite -->|uses sample PDF| DirectExtractPDF
    TestSuite -->|uses sample PDF| ImagePDF

    %% Click Events
    click Demo "https://github.com/rapidai/rapidocrpdf/blob/main/demo.py"
    click CLI "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click API "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click Loader "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click Manager "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click DirectExt "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click OCRExt "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click Aggregator "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/main.py"
    click Logger "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/utils/logger.py"
    click Utils "https://github.com/rapidai/rapidocrpdf/blob/main/rapidocr_pdf/utils/utils.py"
    click TestSuite "https://github.com/rapidai/rapidocrpdf/blob/main/tests/test_main.py"
    click DirectImagePDF "https://github.com/rapidai/rapidocrpdf/blob/main/tests/test_files/direct_and_image.pdf"
    click DirectExtractPDF "https://github.com/rapidai/rapidocrpdf/blob/main/tests/test_files/direct_extract.pdf"
    click ImagePDF "https://github.com/rapidai/rapidocrpdf/blob/main/tests/test_files/image.pdf"
    click Setup "https://github.com/rapidai/rapidocrpdf/blob/main/setup.py"
    click Requirements "https://github.com/rapidai/rapidocrpdf/blob/main/requirements.txt"
    click Cliff "https://github.com/rapidai/rapidocrpdf/blob/main/cliff.toml"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000;
    classDef external fill:#90EE90,stroke:#000;
    classDef io fill:#FFA500,stroke:#000;
    classDef util fill:#D3D3D3,stroke:#000;
```
