# imanoop7/ollama-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/imanoop7/ollama-ocr
- Repository: https://github.com/imanoop7/ollama-ocr

## Overview

##### Project Type and Core Purpose
- Project Type: It is a Python package for performing Optical Character Recognition using state-of-the-art vision language models via Ollama. It also includes a Streamlit-based web interface for interactive use.
- Purpose: The system extracts text from images and PDFs using multiple vision models (LLaVA, llama3.2-vision, granite3.2-vision, moondream, minicpm-v), supports various output formats (markdown, text, JSON, etc.), and allows both single file and batch processing.

##### File Structure to Identify Major Components
- Top-Level Files and Directories:
- README.md, LICENSE, and configuration files (requirements.txt) provide context and deployment information.
- example.ipynb and notebooks in example_notebooks show usage examples and integration tests.
- The src directory contains the main package with a subdirectory "ollama_ocr" that holds:
- app.py: The Streamlit web application interface.
- ocr_processor.py: The core module that implements OCR processing logic including single and batch processing.
- Other Directories:
- input and output folders which likely are used for sample or runtime image input and output storage.

##### Key Components and How They Relate
a. Core OCR Package:
- Component: OCRProcessor (implemented in ocr_processor.py)
- Responsibilities: Accepts user parameters (image path, custom prompts, format type), handles image preprocessing, sends requests to the vision model API (via Ollama), and processes responses.
- Dependencies: Interacts with external Ollama API endpoints and uses configuration settings (such as model names and custom endpoints).

b. Streamlit Web Application:
- Component: Streamlit Frontend (app.py)
- Responsibilities: Provides a user-friendly drag-and-drop interface, manages file uploads, displays image previews, allows language and processing options, and shows real-time processing results.
- Interaction: Uses the OCRProcessor component to perform OCR operations in a graphical environment.

c. External Services and Vision Models:
- Component: Vision Model APIs provided by Ollama.
- Responsibilities: These models (like LLaVA, llama3.2-vision, etc.) are pulled in and used to perform OCR tasks and text extraction.
- Interaction Pattern: The OCRProcessor makes HTTP API calls (through a provided base URL or similar configuration) to these services to retrieve extracted text in various formats.

d. Supporting Modules:
- Examples and Notebooks: Illustrate how to use the package for both interactive (e.g., on Colab) and automated batch processing.
- Configuration and Dependency Files (requirements.txt, .gitignore, etc.): Aid in setting up and deploying the system.

a. Components to Include:
- Client/User Interface:
- Streamlit Web Application (app.py) – responsible for user interaction.
- Example notebooks (illustrating alternative usage scenarios).
- Business Logic Layer:
- OCRProcessor component (ocr_processor.py) that encapsulates OCR logic.
- Image Preprocessing and Batch Processing modules.
- External Integration:
- Vision Model API endpoints (the external service “Ollama” or specific vision models like LLaVA, llama3.2-vision, etc.).
- Optional: The Input and Output storage directories showing the file system interaction points.

b. Relationships and Data Flow:
- Separate lines indicating batch processing loops and handling of parallel processing (max_workers parameter).

c. Architectural Patterns to Highlight:
- Separation of Concerns: Clearly separate the UI (Streamlit app) from the core OCR processing engine.
- Modularity: The design splits the package into submodules (for OCR logic and web interface) which promote reusability.
- API-Based Integration: The communication with external vision models is abstracted through API calls—this is critical and should be clearly depicted.
- Extensibility: Emphasize the custom prompts and multiple output formats as design extensions that could allow future enhancements.

d. Styling Guidelines:
- Web interface (e.g., a blue rectangle for Streamlit).
- Backend processing (e.g., a green rectangle for OCRProcessor).
- External services (e.g., a red oval for Vision Model APIs).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        ST["Streamlit Web Application"]:::ui
        EN["Example Notebooks"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        OCR["OCRProcessor"]:::processor
    end

    %% External Integration Layer
    subgraph "External Services"
        VAPI["Vision Model APIs"]:::external
    end

    %% File Storage Layer
    subgraph "File Storage"
        Input["Input Data Storage"]:::storage
        Output["Output Data Storage"]:::storage
    end

    %% Configuration
    Config["Configuration & Dependencies"]:::config

    %% Data Flow
    Config -->|"setup"| ST
    Config -->|"setup"| OCR

    ST -->|"upload/process"| OCR
    EN -->|"alternativeInvocation"| OCR

    OCR -->|"APICall"| VAPI
    VAPI -->|"Response"| OCR

    OCR -->|"resultsDisplay"| ST

    OCR -->|"batchRead"| Input
    OCR -->|"batchWrite"| Output

    %% Click Events
    click ST "https://github.com/imanoop7/ollama-ocr/blob/main/src/ollama_ocr/app.py"
    click OCR "https://github.com/imanoop7/ollama-ocr/blob/main/src/ollama_ocr/ocr_processor.py"
    click EN "https://github.com/imanoop7/ollama-ocr/tree/main/example_notebooks"
    click Input "https://github.com/imanoop7/ollama-ocr/tree/main/input"
    click Output "https://github.com/imanoop7/ollama-ocr/tree/main/output"
    click Config "https://github.com/imanoop7/ollama-ocr/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#add8e6,stroke:#0000FF,stroke-width:2px;
    classDef processor fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#FF0000,stroke-width:2px;
    classDef storage fill:#FFFFCC,stroke:#CCCC00,stroke-width:2px;
    classDef config fill:#e0e0e0,stroke:#888888,stroke-width:2px;
```
