# getomni-ai/zerox architecture

> Architecture diagram of the GitHub repository getomni-ai/zerox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getomni-ai/zerox
- Repository: https://github.com/getomni-ai/zerox

## Overview

Zerox is a document-to-Markdown OCR SDK with Node.js and Python implementations. The principal workflow accepts a document, prepares page images, sends pages to vision models, and aggregates Markdown; Node also supports structured extraction. The graph separates orchestration, document processing, model integrations, and Python’s page-processing layer. Relationships for the sampled paths are grounded in source excerpts or the README; some broader capabilities are documented but their implementation details were not sampled.

Main entry points: [`node-zerox/src/index.ts`](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/index.ts) (OCR orchestration), [`node-zerox/src/models/index.ts`](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/index.ts) (Provider selection), [`py_zerox/pyzerox/models/modellitellm.py`](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/models/modellitellm.py) (LiteLLM adapter), [`py_zerox/pyzerox/core/zerox.py`](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/core/zerox.py) (OCR orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node_api["Node SDK"]
  node_node_entry["OCR orchestration<br/>[index.ts]"]
end

subgraph group_node_processing["Node Processing"]
  node_node_files["File preparation<br/>[file.ts]"]
  node_node_images["Image cleanup<br/>[image.ts]"]
  node_node_common["Shared helpers<br/>[common.ts]"]
  node_node_tesseract["Orientation workers<br/>[tesseract.ts]"]
end

subgraph group_node_models["Node Models"]
  node_node_model_utils["Model utilities<br/>[model.ts]"]
  node_node_dispatch["Provider selection<br/>[index.ts]"]
  node_node_openai["OpenAI adapter<br/>[openAI.ts]"]
  node_node_azure["Azure adapter<br/>[azure.ts]"]
  node_node_bedrock["Bedrock adapter<br/>[bedrock.ts]"]
  node_node_google["Google adapter<br/>[google.ts]"]
end

subgraph group_python_api["Python SDK"]
  node_python_entry["OCR orchestration<br/>[zerox.py]"]
  node_python_model["LiteLLM adapter<br/>[modellitellm.py]"]
  node_python_messages["Messages and prompts<br/>[messages.py]"]
  node_python_prompts["Model prompts<br/>[prompts.py]"]
  node_python_errors["Domain exceptions<br/>[exceptions.py]"]
end

subgraph group_python_processing["Python Processing"]
  node_python_pdf["PDF conversion<br/>[pdf.py]"]
  node_python_image["Image utilities<br/>[image.py]"]
  node_python_text["Markdown formatting<br/>[text.py]"]
end

node_user(("SDK caller"))
node_vision_services{{"Vision model APIs"}}
node_python_user(("Python SDK caller"))
node_litellm{{"LiteLLM services"}}

node_user -->|"submits document"| node_node_entry
node_node_entry -->|"prepares input"| node_node_files
node_node_entry -->|"cleans images"| node_node_images
node_node_entry -->|"manages workers"| node_node_tesseract
node_node_entry -->|"creates model"| node_node_dispatch
node_node_dispatch -->|"validates parameters"| node_node_model_utils
node_node_dispatch -->|"selects provider"| node_node_openai
node_node_dispatch -->|"selects provider"| node_node_azure
node_node_dispatch -->|"selects provider"| node_node_bedrock
node_node_dispatch -->|"selects provider"| node_node_google
node_node_openai -->|"requests completion"| node_vision_services
node_node_azure -->|"requests completion"| node_vision_services
node_node_bedrock -->|"requests completion"| node_vision_services
node_node_google -->|"requests completion"| node_vision_services
node_node_entry -->|"returns Markdown"| node_user
node_python_user -->|"submits document"| node_python_entry
node_python_entry -->|"initializes model"| node_python_model
node_python_entry -->|"converts and processes pages"| node_python_pdf
node_python_pdf -->|"saves page images"| node_python_image
node_python_pdf -->|"formats Markdown"| node_python_text
node_python_pdf -->|"requests page completion"| node_python_model
node_python_model -->|"encodes images"| node_python_image
node_python_model -->|"calls completion API"| node_litellm
node_python_model -->|"uses defaults"| node_python_prompts
node_python_model -->|"formats errors"| node_python_messages
node_python_entry -->|"raises domain errors"| node_python_errors
node_python_entry -->|"returns Markdown"| node_python_user

click node_node_entry "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/index.ts"
click node_node_files "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/file.ts"
click node_node_images "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/image.ts"
click node_node_common "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/common.ts"
click node_node_tesseract "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/tesseract.ts"
click node_node_model_utils "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/model.ts"
click node_node_dispatch "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/index.ts"
click node_node_openai "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/openAI.ts"
click node_node_azure "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/azure.ts"
click node_node_bedrock "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/bedrock.ts"
click node_node_google "https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/google.ts"
click node_python_entry "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/core/zerox.py"
click node_python_pdf "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/pdf.py"
click node_python_image "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/image.py"
click node_python_text "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/text.py"
click node_python_model "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/models/modellitellm.py"
click node_python_messages "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/constants/messages.py"
click node_python_prompts "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/constants/prompts.py"
click node_python_errors "https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/errors/exceptions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_entry toneBlue
class node_node_files,node_node_images,node_node_common,node_node_tesseract toneAmber
class node_node_model_utils,node_node_dispatch,node_node_openai,node_node_azure,node_node_bedrock,node_node_google,node_vision_services toneMint
class node_python_entry,node_python_model,node_python_messages,node_python_prompts,node_python_errors toneRose
class node_python_pdf,node_python_image,node_python_text,node_user,node_python_user,node_litellm toneIndigo
```

## Components

### Node SDK

- [OCR orchestration](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/index.ts): `node-zerox/src/index.ts`

### Node Processing

- [File preparation](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/file.ts): `node-zerox/src/utils/file.ts`
- [Image cleanup](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/image.ts): `node-zerox/src/utils/image.ts`
- [Shared helpers](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/common.ts): `node-zerox/src/utils/common.ts`
- [Orientation workers](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/tesseract.ts): `node-zerox/src/utils/tesseract.ts`

### Node Models

- [Model utilities](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/utils/model.ts): `node-zerox/src/utils/model.ts`
- [Provider selection](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/index.ts): `node-zerox/src/models/index.ts`
- [OpenAI adapter](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/openAI.ts): `node-zerox/src/models/openAI.ts`
- [Azure adapter](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/azure.ts): `node-zerox/src/models/azure.ts`
- [Bedrock adapter](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/bedrock.ts): `node-zerox/src/models/bedrock.ts`
- [Google adapter](https://github.com/getomni-ai/zerox/blob/main/node-zerox/src/models/google.ts): `node-zerox/src/models/google.ts`

### Python SDK

- [OCR orchestration](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/core/zerox.py): `py_zerox/pyzerox/core/zerox.py`
- [LiteLLM adapter](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/models/modellitellm.py): `py_zerox/pyzerox/models/modellitellm.py`
- [Messages and prompts](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/constants/messages.py): `py_zerox/pyzerox/constants/messages.py`
- [Model prompts](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/constants/prompts.py): `py_zerox/pyzerox/constants/prompts.py`
- [Domain exceptions](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/errors/exceptions.py): `py_zerox/pyzerox/errors/exceptions.py`

### Python Processing

- [PDF conversion](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/pdf.py): `py_zerox/pyzerox/processor/pdf.py`
- [Image utilities](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/image.py): `py_zerox/pyzerox/processor/image.py`
- [Markdown formatting](https://github.com/getomni-ai/zerox/blob/main/py_zerox/pyzerox/processor/text.py): `py_zerox/pyzerox/processor/text.py`

### Other components

- **SDK caller**
- **Vision model APIs**
- **Python SDK caller**
- **LiteLLM services**

## Connections

- SDK caller → OCR orchestration: submits document
- OCR orchestration → File preparation: prepares input (evidence: `node-zerox/src/index.ts`)
- OCR orchestration → Image cleanup: cleans images (evidence: `node-zerox/src/index.ts`)
- OCR orchestration → Orientation workers: manages workers (evidence: `node-zerox/src/index.ts`)
- OCR orchestration → Provider selection: creates model (evidence: `node-zerox/src/index.ts`)
- Provider selection → Model utilities: validates parameters (evidence: `node-zerox/src/models/index.ts`)
- Provider selection → OpenAI adapter: selects provider (evidence: `node-zerox/src/models/index.ts`)
- Provider selection → Azure adapter: selects provider (evidence: `node-zerox/src/models/index.ts`)
- Provider selection → Bedrock adapter: selects provider (evidence: `node-zerox/src/models/index.ts`)
- Provider selection → Google adapter: selects provider (evidence: `node-zerox/src/models/index.ts`)
- OpenAI adapter → Vision model APIs: requests completion
- Azure adapter → Vision model APIs: requests completion
- Bedrock adapter → Vision model APIs: requests completion
- Google adapter → Vision model APIs: requests completion
- OCR orchestration → SDK caller: returns Markdown
- Python SDK caller → OCR orchestration: submits document
- OCR orchestration → LiteLLM adapter: initializes model (evidence: `py_zerox/pyzerox/core/zerox.py`)
- OCR orchestration → PDF conversion: converts and processes pages (evidence: `py_zerox/pyzerox/core/zerox.py`)
- PDF conversion → Image utilities: saves page images (evidence: `py_zerox/pyzerox/processor/pdf.py`)
- PDF conversion → Markdown formatting: formats Markdown (evidence: `py_zerox/pyzerox/processor/pdf.py`)
- PDF conversion → LiteLLM adapter: requests page completion (evidence: `py_zerox/pyzerox/processor/pdf.py`)
- LiteLLM adapter → Image utilities: encodes images (evidence: `py_zerox/pyzerox/models/modellitellm.py`)
- LiteLLM adapter → LiteLLM services: calls completion API (evidence: `py_zerox/pyzerox/models/modellitellm.py`)
- LiteLLM adapter → Model prompts: uses defaults (evidence: `py_zerox/pyzerox/models/modellitellm.py`)
- LiteLLM adapter → Messages and prompts: formats errors (evidence: `py_zerox/pyzerox/models/modellitellm.py`)
- OCR orchestration → Domain exceptions: raises domain errors (evidence: `py_zerox/pyzerox/core/zerox.py`)
- OCR orchestration → Python SDK caller: returns Markdown
