# ses4255/versatile-ocr-program architecture

> Architecture diagram of the GitHub repository ses4255/versatile-ocr-program, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ses4255/versatile-ocr-program
- Repository: https://github.com/ses4255/versatile-ocr-program

## Overview

##### Project Type & Purpose
- The README also highlights two main processing steps: an initial OCR extraction phase and a later semantic interpretation/final output phase. In addition, the system integrates multiple external APIs (Google Vision API, OpenAI API, etc.) and specialized tools like DocLayout-YOLO.

##### Analyzing the File Structure
- Notice that there are version-specific directories (v1.0_initial and v2.0_initial) each containing key Python modules such as:
– advanced_ocr.py
– custom_doclayout_yolo.py
– ocr_stage1.py
– ocr_stage2.py
– Dockerfile (for containerized deployment)
- The duplication of files in version-specific folders signals an evolutionary design. However, the core OCR pipeline and processing scripts are consistent between versions.
- Other items like patch_notes, sample_images, and setup/guide files provide auxiliary information but aren’t directly part of the processing flow.

A. Main Components:
– Input Layer:
- PDF/Document Ingestion: The OCR system starts with receiving complex exam-style PDFs.
- Sample input components (documents/images) are provided in the sample_images folder.
– Stage 1 – Initial OCR Extraction:
- Module (ocr_stage1.py) handling raw extraction.
– Stage 2 – Semantic Interpretation & Final Output:
- Ocr_stage2.py module which refines the content, adds natural language summaries, and formats the output into structured formats (JSON/Markdown).
- This component may interact with external services (e.g., Google Cloud Vision API for image and text detection) as detailed in the technical implementation.
– Auxiliary/Supporting Components:
- Advanced OCR Module (advanced_ocr.py) and custom document layout processing (custom_doclayout_yolo.py) which may sit alongside the core stages to enhance accuracy.
- External APIs and Services:
- Google Vision API for text, table, and image processing.
- Other third-party services like MathPix OCR, OpenAI API, etc. in the extended pipeline.
– Container and Deployment:
- A Docker container (referencing the Dockerfile) that encapsulates the runtime environment ensuring consistency across deployments.

B. Relationships and Data Flow:
1. User/External Input (PDF Document) →
2. Stage 1: OCR Extraction (ocr_stage1.py, implements layout and region detection) →
3. Intermediate Data Storage/Representation (extracted raw data, coordinates, cropped images) →
4. Stage 2: Semantic Interpretation (ocr_stage2.py, converts raw data into human-readable and structured formats) →
5. Final Output (JSON/Markdown, the annotated and contextual data ready for ML training).
– Also show ancillary connections where the OCR extraction and enhancement modules may call external APIs or use libraries such as DocLayout-YOLO and Google Vision.

C. Architectural Patterns / Design Principles:
– Pipeline Architecture: Clearly illustrate the two-stage processing pipeline.
– Modularity: Emphasize how separate modules (each in a distinct Python file) work in tandem while remaining decoupled; this modularity facilitates version updates and testing.
– Containerized Deployment: Highlight the Docker container promoting reproducible environments and simplifying deployment.

D. Technology Stack:
– Include labels for frameworks and libraries such as DocLayout-YOLO, OpenCV, and Google Vision API.
– If relevant, note that the project leverages external image processing and OCR enhancements from external AI models (e.g., Gemini Pro Vision, MathPix OCR).

## Diagram (Mermaid)

```mermaid
flowchart TD
    InputPDF["PDF Document Input"]:::input
    Ingest["PDF/Document Ingestion"]:::input
    OCR1["OCR Extraction (ocr_stage1.py)"]:::process
    InterData["Intermediate Raw Data"]:::process
    OCR2["Semantic Interpretation (ocr_stage2.py)"]:::process
    Output["Final Structured Output (JSON/Markdown)"]:::process
    AdvancedOCR["Advanced OCR Module (advanced_ocr.py)"]:::process
    CustomDocLayout["DocLayout-YOLO (custom_doclayout_yolo.py)"]:::process
    ExternalAPIs["External APIs (GoogleVision,OpenAI,MathPix)"]:::external
    Container["Docker Container (Dockerfile)"]:::container

    InputPDF --> Ingest
    Ingest --> OCR1
    OCR1 --> InterData
    InterData --> OCR2
    OCR2 --> Output

    OCR1 --> AdvancedOCR
    OCR1 --> CustomDocLayout
    OCR2 --> ExternalAPIs

    Container --> Ingest
    Container --> OCR1
    Container --> OCR2

    classDef input fill:#fdd835,stroke:#333,stroke-width:2px
    classDef process fill:#4fc3f7,stroke:#333,stroke-width:2px
    classDef external fill:#81c784,stroke:#333,stroke-width:2px
    classDef container fill:#e1bee7,stroke:#333,stroke-width:2px

    class InputPDF,Ingest input
    class OCR1,InterData,OCR2,Output,AdvancedOCR,CustomDocLayout process
    class ExternalAPIs external
    class Container container

    click Ingest "https://github.com/ses4255/versatile-ocr-program/tree/main/sample_images"
    click OCR1 "https://github.com/ses4255/versatile-ocr-program/blob/main/v1.0_initial/ocr_stage1.py"
    click OCR2 "https://github.com/ses4255/versatile-ocr-program/blob/main/v1.0_initial/ocr_stage2.py"
    click AdvancedOCR "https://github.com/ses4255/versatile-ocr-program/blob/main/v1.0_initial/advanced_ocr.py"
    click CustomDocLayout "https://github.com/ses4255/versatile-ocr-program/blob/main/v1.0_initial/custom_doclayout_yolo.py"
    click Container "https://github.com/ses4255/versatile-ocr-program/tree/main/v1.0_initial/Dockerfile"
```
