# huridocs/pdf-document-layout-analysis architecture

> Architecture diagram of the GitHub repository huridocs/pdf-document-layout-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huridocs/pdf-document-layout-analysis
- Repository: https://github.com/huridocs/pdf-document-layout-analysis
- Video tour (about a minute): https://gitdiagram.com/huridocs/pdf-document-layout-analysis/video

## Overview

##### Main Components

a) Core Service Layer:
- PDF Processing Service (Main API endpoint)
- OCR Service (Tesseract/ocrmypdf integration)
- Layout Analysis Service (with two model paths)

b) Model Components:
- Vision Grid Transformer (VGT) Pipeline
- LightGBM Models Pipeline
- Model Configuration Management

c) Processing Components:
- PDF Feature Extraction
- Text Extraction
- Table/Formula Extraction
- Table of Contents Processing
- Visualization Generation

d) Data Models and Types:
- PDF Segments
- Token Types
- Page Labels

##### Architectural Patterns to Highlight

- Microservices-style architecture with Docker containerization
- Parallel processing paths (Fast vs. GPU-intensive)
- Pipeline pattern for document processing
- Plugin-style architecture for different extraction formats

**┌─ API Layer ─────────────────────────────────────────┐**
- Main Endpoint (/)                                 │
- OCR Endpoint (/ocr)                              │
- ┘
- ↓
**┌─ Processing Orchestration Layer ────────────────────┐**
- ┌─────────────┐        ┌─────────────┐    │
- Fast Path  │        │   VGT Path  │    │
- ┘        └─────────────┘    │
- ┘
- ↓
**┌─ Core Processing Components ────────────────────────┐**
- PDF Feature Extraction                           │
- Layout Analysis                                  │
- OCR Processing                                   │
- Table/Formula Extraction                         │
- ┘
- ↓
**┌─ Model Layer ────────────────────────────────────────┐**
- ┌─ LightGBM ─┐    ┌─ VGT ─┐                         │
- Token Type │    │ Visual │                         │
- Segmentation│    │ Model  │                         │
- ┘    └───────┘                         │
- ┘
- ↓
**┌─ Output Processing Layer ──────────────────────────┐**
- Reading Order Processing                         │
- Visualization Generation                         │
- ┘

##### Important Flows to Highlight
- Document input flow
- Parallel processing paths (Fast vs. VGT)
- OCR integration points
- Model selection logic
- Output generation paths

##### Additional Elements
- Docker container boundaries
- GPU vs. CPU processing paths
- Data format transformations
- External service integration points

##### Technical Details
- Model specifications (11 categories)
- Performance metrics
- Resource requirements
- Supported file formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph API
        MainAPI["Main API Service"]
        OCREndpoint["OCR Endpoint"]
        VisEndpoint["Visualization Endpoint"]
    end

    subgraph ProcessingOrchestration
        direction TB
        FastPath["Fast Processing Path"]
        VGTPath["VGT Processing Path"]
    end

    subgraph CoreProcessing
        direction TB
        PDFFeatures["PDF Feature Extraction"]
        LayoutAnalysis["Layout Analysis"]
        OCRProcess["OCR Processing"]
        TableFormula["Table/Formula Extraction"]
    end

    subgraph ModelLayer
        direction TB
        subgraph LightGBM
            TokenType["Token Type Model"]
            Segmentation["Segmentation Model"]
        end
        subgraph VGT
            VisionModel["Vision Grid Transformer"]
            BrosConfig["BROS Configuration"]
        end
    end

    subgraph OutputProcessing
        direction TB
        SegmentGen["Segment Box Generation"]
        ReadingOrder["Reading Order Processing"]
        Visualization["Visualization Generation"]
        TOC["Table of Contents Processing"]
    end

    %% Connections
    MainAPI --> ProcessingOrchestration
    OCREndpoint --> OCRProcess
    VisEndpoint --> Visualization

    ProcessingOrchestration --> CoreProcessing
    CoreProcessing --> ModelLayer
    ModelLayer --> OutputProcessing

    %% Click events
    click MainAPI "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/app.py"
    click OCRProcess "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/ocr/ocr_pdf.py"
    click LayoutAnalysis "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/pdf_layout_analysis/run_pdf_layout_analysis.py"
    click VisionModel "https://github.com/huridocs/pdf-document-layout-analysis/tree/main/src/ditod/"
    click VGTPath "https://github.com/huridocs/pdf-document-layout-analysis/tree/main/src/vgt/"
    click LightGBM "https://github.com/huridocs/pdf-document-layout-analysis/tree/main/src/pdf_tokens_type_trainer/"
    click PDFFeatures "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/pdf_features/PdfFeatures.py"
    click TableFormula "https://github.com/huridocs/pdf-document-layout-analysis/tree/main/src/extraction_formats/"
    click TOC "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/toc/extract_table_of_contents.py"
    click Visualization "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/visualization/get_visualization.py"
    click SegmentGen "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/data_model/SegmentBox.py"
    click TokenType "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/pdf_token_type_labels/TokenType.py"
    click FastPath "https://github.com/huridocs/pdf-document-layout-analysis/tree/main/src/fast_trainer/"
    click BrosConfig "https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/bros/configuration_bros.py"

    %% Styling
    classDef api fill:#2374ab
    classDef processing fill:#48a9a6
    classDef model fill:#e4cc37
    classDef output fill:#d96459
    classDef external fill:#9c528b

    class MainAPI,OCREndpoint,VisEndpoint api
    class PDFFeatures,LayoutAnalysis,OCRProcess,TableFormula processing
    class TokenType,Segmentation,VisionModel,BrosConfig model
    class SegmentGen,ReadingOrder,Visualization,TOC output
    class FastPath,VGTPath processing
```
