# sirfz/tesserocr architecture

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

- Interactive diagram: https://gitdiagram.com/sirfz/tesserocr
- Repository: https://github.com/sirfz/tesserocr

## Overview

##### Project type and purpose
- This is an open-source Python library (wrapper) around the Tesseract OCR C++ API.
- Its main purpose is to expose Tesseract’s OCR functionality to Python users in a “Pythonic” way, support Pillow images, and leverage Cython for performance and GIL release.

##### File structure
Top-level directories/files:
- .github/workflows, .travis.yml, tox.ini, Dockerfile – CI/CD and packaging pipelines
- build-scripts – platform-specific install scripts for libtesseract and dependencies
- tesserocr/ – Cython sources (`.pyx`, `.pxd`), C glue (`tesserocr.c`), Python shim (`tesserocr.pyx`), type stubs
- tests/ – unit tests for the public API
- setup.py, pyproject.toml, requirements*.txt – build configuration
- Windows.build.md – Windows-specific build instructions

##### README for additional insights
- Confirms dependencies on libtesseract and libleptonica, optional Pillow.
- Describes usage patterns: `PyTessBaseAPI` context manager, helper functions (`image_to_text`, `file_to_text`).
- Mentions concurrency (GIL release).

##### Components
a. Core runtime components:
1. Python Application Code (user code or helper scripts)
2. tesserocr Python API (pure-Python entry points)
3. Cython wrapper module (compiled extension)
4. Tesseract C++ library (libtesseract)
5. Leptonica C library (libleptonica)
6. Pillow (optional; provides PIL.Image objects)
7. Image files (JPG, TIFF, etc.)
b. Build & packaging components:
1. setup.py / pyproject.toml (build orchestrator)
2. Cython (compile .pyx to C)
3. Compiler toolchain (gcc/clang or MSVC on Windows)
4. Platform-specific build scripts (.github/build-scripts, Windows.build.md)
5. CI pipelines (GitHub Actions, Travis CI, Dockerfile)
c. Test & quality components:
1. tests/
2. tox (matrix testing)
3. coverage/linters (if present)

##### Relationships and data flows
- At runtime:
User Code → (calls) tesserocr API (Python module) → (invokes) Cython extension → (binds into) libtesseract → (uses) libleptonica to preprocess images → returns OCR text back up the chain.
- Optional: Pillow provides in-memory image objects to the Cython layer.
- Environment variables (TESSDATA_PREFIX) affect runtime resource lookup.
- Concurrency: Cython releases the GIL when calling into Tesseract, allowing parallel image processing.
- Build-time: setup.py invokes Cython → compiler → links to libtesseract & libleptonica → produces a platform-specific wheel. CI scripts automate builds for Linux, macOS, Windows.

##### Architectural patterns & design principles
- Layered architecture:
1. Presentation (Python API / helper functions)
2. Adapter layer (Cython extension)
3. External service layer (native OCR libraries)
- Dependency inversion: high-level Python code depends on abstractions (Cython stubs), the low-level C++ code is injected via dynamic linking.
- Concurrency safe: GIL released in the native calls.
- Cross-platform build orchestration via scripted CI.

##### Don’t overthink—capture all meaningful components
- Even small scripts in .github/build-scripts matter for understanding cross-platform builds.
- Both code-centric (Cython, Python) and infrastructure-centric (CI, Docker) elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Layer
    subgraph "Runtime Layer"
        direction TB
        UserCode["User Code"]:::python
        API["tesserocr Python API"]:::python
        CythonSrc["Cython Wrapper Source (.pyx)"]:::python
        CGlue["C Glue Module (.c)"]:::python
        TessDefs["Tesseract Definitions (.pxd)"]:::native
        Tesseract["libtesseract (C++)"]:::native
        Leptonica["libleptonica (C)"]:::native
        Pillow["Pillow (optional)"]:::optional
        ImageFiles["Image Files"]:::native
        Env["Env Vars (TESSDATA_PREFIX)"]:::native
    end

    UserCode -->|"calls"| API
    API -->|"imports"| CythonSrc
    CythonSrc -->|"generates"| CGlue
    CGlue -->|"binds"| TessDefs
    TessDefs -->|"calls Tesseract API"| Tesseract
    Tesseract -->|"uses"| Leptonica
    Pillow -->|"provides PIL.Image"| CythonSrc
    ImageFiles -->|"loaded by"| API
    Env -->|"configures"| Tesseract

    %% Build/CI Layer
    subgraph "Build & CI Layer"
        direction TB
        BuildOrch["Build Orchestrator\n(setup.py, pyproject.toml)"]:::infra
        CythonComp["Cython Compiler"]:::infra
        Toolchain["Compiler Toolchain"]:::infra
        BuildScripts["Platform-specific Build Scripts"]:::infra
        CI["CI/CD Pipelines"]:::infra
        Docker["Dockerfile"]:::infra
    end

    BuildOrch -->|"runs"| CythonComp
    CythonComp -->|"compiles .pyx"| CGlue
    CythonComp -->|"generates C code"| CGlue
    CGlue -->|"links with"| Tesseract
    CGlue -->|"links with"| Leptonica
    BuildOrch -->|"invokes"| Toolchain
    BuildScripts -->|"install deps on hosts"| Toolchain
    CI -->|"automates builds on Linux/macOS/Windows"| BuildOrch
    CI -->|"runs"| Docker
    CI -->|"runs"| BuildScripts

    %% Test Layer
    subgraph "Test & Quality Layer"
        direction TB
        Tests["Unit Tests"]:::infra
        Tox["tox.ini"]:::infra
        Coverage["Coverage & Linters"]:::infra
    end

    Tests -->|"validates API"| API
    Tox -->|"runs matrix tests"| Tests
    CI -->|"executes"| Tox
    CI -->|"executes"| Coverage

    %% Experimental Module
    Exp["Experimental Cython Module"]:::python

    Exp -.->|"prototype"| CythonSrc

    %% Click Events
    click API "https://github.com/sirfz/tesserocr/blob/master/tesserocr/__init__.py"
    click CythonSrc "https://github.com/sirfz/tesserocr/blob/master/tesserocr/tesserocr.pyx"
    click CGlue "https://github.com/sirfz/tesserocr/blob/master/tesserocr/tesserocr.c"
    click TessDefs "https://github.com/sirfz/tesserocr/blob/master/tesserocr/tesseract.pxd"
    click Exp "https://github.com/sirfz/tesserocr/blob/master/tesserocr_experiment.pyx"
    click BuildOrch "https://github.com/sirfz/tesserocr/blob/master/setup.py"
    click BuildScripts "https://github.com/sirfz/tesserocr/tree/master/.github/build-scripts"
    click CI "https://github.com/sirfz/tesserocr/blob/master/.github/workflows/build.yml"
    click Tests "https://github.com/sirfz/tesserocr/blob/master/tests/__init__.py"
    click Tox "https://github.com/sirfz/tesserocr/blob/master/tox.ini"

    %% Styles
    classDef python fill:#d5f5e3,stroke:#27ae60,stroke-width:1px
    classDef native fill:#aed6f1,stroke:#2980b9,stroke-width:1px
    classDef infra fill:#f9e79f,stroke:#d68910,stroke-width:1px
    classDef optional fill:none,stroke:#95a5a6,stroke-dasharray:5 5,stroke-width:1px
```
