# bytefer/ollama-ocr architecture

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

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

## Overview

1. This is a small TypeScript/Node.js library, not an application server. Its main job is to take a local image file, send it to a running Ollama instance with a vision model, and return extracted text.

2. The primary public boundary is `src/index.ts`. That is the package entry point and the API surface consumers import from: the OCR function, default prompts, and the custom error types/codes referenced in the README.

3. `src/config.ts` centralizes the library’s defaults and policy values. Based on the README, this is where you’d expect the built-in OCR prompts, markdown prompt, supported image types, default model names, and any Ollama connection settings to live.

4. `src/util.ts` is the support layer for local pre-processing and validation. Its responsibilities are likely file/path checks, image-type validation, file reading/encoding, and small helpers used by the OCR pipeline.

5. The core runtime flow is: caller provides `filePath` plus optional `model` and `systemPrompt` -> the library validates the file -> reads the image from disk -> builds an Ollama vision request -> sends it to the local Ollama server -> returns the model’s text response.

6. The external service boundary is important here: the only networked dependency is a locally running Ollama server. The actual OCR capability comes from whichever vision model is installed in Ollama, such as `llama3.2-vision` or `minicpm-v`.

7. Input handling is intentionally narrow. The README says the library supports `.jpg`, `.jpeg`, and `.png` only, so format checking is part of the architecture rather than a loose runtime detail. Unsupported files should fail fast through the custom error system.

8. Error handling is a first-class subsystem. The documented `LlamaOCRError` and `ErrorCode` values separate failure modes such as missing file, unsupported type, Ollama connection/server issues, and OCR processing failures. That makes the library’s boundary behavior explicit for consumers.

9. Output formatting is driven by prompts rather than separate post-processing. There are at least two prompt modes: plain OCR and markdown-preserving OCR. That means text structure preservation is mostly delegated to the vision model through prompt engineering.

10. The test area is lightweight and fixture-based. `test/images` and `test/test.txt` indicate local sample inputs and expected-output-style assets, with `test/index.test.ts` likely covering the public API and error paths end to end against those fixtures.

11. There is no persistent storage, queue, auth layer, or web UI in this repo. The architecture is a single-package library with a simple dependency chain: consumer code -> OCR library -> filesystem + Ollama server -> text result.

12. For an architecture diagram, the key boxes are: application consumer, exported OCR library, config/constants, utility helpers, local image files, Ollama server, and installed vision model. The main data flow is one-way from file path to model request to extracted text, with errors branching back to the caller.

Main entry points: [`src/index.ts`](https://github.com/bytefer/ollama-ocr/blob/main/src/index.ts) (API entry), [`test/index.test.ts`](https://github.com/bytefer/ollama-ocr/blob/main/test/index.test.ts) (Test suite), [`src/util.ts`](https://github.com/bytefer/ollama-ocr/blob/main/src/util.ts) (Helpers), [`src/config.ts`](https://github.com/bytefer/ollama-ocr/blob/main/src/config.ts) (Defaults)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_consumer(("Consumer<br/>caller"))
  node_index["API entry<br/>src/index.ts<br/>[index.ts]"]
  node_errors{{"Errors<br/>error model"}}
  node_text["Extracted text<br/>result"]
end

subgraph group_runtime["OCR Runtime"]
  node_config["Defaults<br/>src/config.ts<br/>[config.ts]"]
  node_util["Helpers<br/>src/util.ts<br/>[util.ts]"]
  node_ocr["OCR flow<br/>pipeline"]
  node_prompt_plain["OCR prompt"]
  node_prompt_md["Markdown prompt"]
end

subgraph group_external["External Boundaries"]
  node_file_path["Image path<br/>input file"]
  node_fs[("Filesystem<br/>local I/O")]
  node_image["Image file<br/>fixture/input"]
  node_ollama[("Ollama server<br/>local service")]
  node_vision{{"Vision model<br/>installed model"}}
end

subgraph group_tests["Tests"]
  node_tests["Test suite<br/>[index.test.ts]"]
  node_fixture_text["Expected text<br/>fixture<br/>[test.txt]"]
end

node_consumer -->|"imports"| node_index
node_index -->|"exposes"| node_ocr
node_index -->|"re-exports"| node_config
node_index -->|"re-exports"| node_errors
node_ocr -->|"uses"| node_util
node_ocr -->|"reads defaults"| node_config
node_ocr -->|"selects"| node_prompt_plain
node_ocr -->|"selects"| node_prompt_md
node_ocr -->|"accepts"| node_file_path
node_util -->|"validates"| node_fs
node_fs -->|"reads"| node_image
node_ocr -->|"requests"| node_ollama
node_ollama -->|"runs"| node_vision
node_vision -->|"returns"| node_text
node_ocr -->|"throws"| node_errors
node_tests -->|"verifies"| node_index
node_tests -->|"uses"| node_image
node_tests -->|"compares"| node_fixture_text

click node_index "https://github.com/bytefer/ollama-ocr/blob/main/src/index.ts"
click node_config "https://github.com/bytefer/ollama-ocr/blob/main/src/config.ts"
click node_util "https://github.com/bytefer/ollama-ocr/blob/main/src/util.ts"
click node_image "https://github.com/bytefer/ollama-ocr/tree/main/test/images"
click node_tests "https://github.com/bytefer/ollama-ocr/blob/main/test/index.test.ts"
click node_fixture_text "https://github.com/bytefer/ollama-ocr/blob/main/test/test.txt"

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_consumer,node_index,node_errors,node_text toneBlue
class node_config,node_util,node_ocr,node_prompt_plain,node_prompt_md toneAmber
class node_file_path,node_fs,node_image,node_ollama,node_vision toneMint
class node_tests,node_fixture_text toneRose
```

## Components

### Public API

Package entry point and consumer-facing surface

- **Consumer**: caller · Application or script importing the library
- [API entry](https://github.com/bytefer/ollama-ocr/blob/main/src/index.ts): src/index.ts · Exports OCR function, prompts, and error types · `src/index.ts`
- **Errors**: error model · LlamaOCRError and ErrorCode boundary for failures
- **Extracted text**: result · OCR text returned to caller

### OCR Runtime

Validation, request building, and model execution

- [Defaults](https://github.com/bytefer/ollama-ocr/blob/main/src/config.ts): src/config.ts · Built-in prompts, model defaults, image types, and Ollama settings · `src/config.ts`
- [Helpers](https://github.com/bytefer/ollama-ocr/blob/main/src/util.ts): src/util.ts · File checks, image validation, encoding, and small pipeline helpers · `src/util.ts`
- **OCR flow**: pipeline · Validates input, builds request, and returns extracted text
- **OCR prompt**: prompt · Default extraction prompt
- **Markdown prompt**: prompt · Prompt tuned to preserve markdown structure

### External Boundaries

Filesystem and Ollama dependencies

- **Image path**: input file · Local jpg, jpeg, or png file path
- **Filesystem**: local I/O · Reads and validates local image files
- [Image file](https://github.com/bytefer/ollama-ocr/tree/main/test/images): fixture/input · Local image content sent to OCR · `test/images`
- **Ollama server**: local service · Running local Ollama API endpoint
- **Vision model**: installed model · Installed multimodal model such as llama3.2-vision or minicpm-v

### Tests

Fixture-based verification of public behavior

- [Test suite](https://github.com/bytefer/ollama-ocr/blob/main/test/index.test.ts): test · Public API and error-path coverage · `test/index.test.ts`
- [Expected text](https://github.com/bytefer/ollama-ocr/blob/main/test/test.txt): fixture · Sample output/reference text · `test/test.txt`

## Connections

- Consumer → API entry: imports · Consumer uses the package entry point
- API entry → OCR flow: exposes · Public OCR function is exported from the package
- API entry → Defaults: re-exports · Default prompts and library constants are surfaced to consumers
- API entry → Errors: re-exports · Custom error types and codes are part of the public API
- OCR flow → Helpers: uses · Pipeline relies on helpers for validation and file handling
- OCR flow → Defaults: reads defaults · Uses built-in prompts, models, and policy values
- OCR flow → OCR prompt: selects · Default OCR prompt mode
- OCR flow → Markdown prompt: selects · Markdown-preserving prompt mode
- OCR flow → Image path: accepts · Input begins as a local file path
- Helpers → Filesystem: validates · Checks existence, extension, and readable file content
- Filesystem → Image file: reads · Local image bytes are loaded from disk
- OCR flow → Ollama server: requests · Sends vision OCR request to local Ollama server
- Ollama server → Vision model: runs · Installed model performs the OCR inference
- Vision model → Extracted text: returns · Model response is surfaced as extracted text
- OCR flow → Errors: throws · Unsupported type, missing file, connection, and processing failures
- Test suite → API entry: verifies · Exercises the public API boundary
- Test suite → Image file: uses · Fixture images drive end-to-end checks
- Test suite → Expected text: compares · Expected output-style fixture for assertions
