# bhimrazy/receipt-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/bhimrazy/receipt-ocr
- Repository: https://github.com/bhimrazy/receipt-ocr
- Video tour (about a minute): https://gitdiagram.com/bhimrazy/receipt-ocr/video

## Overview

Receipt OCR Engine offers two paths: a structured-data package that sends receipt images and a requested schema to an OpenAI-compatible vision model, then parses its response; and a Tesseract path that detects and rectifies the receipt before returning raw text. Users can start either path through a CLI or HTTP API. The graph follows sampled calls; the README documents additional LLM-compatible providers, but the provider implementation is OpenAI-compatible. The production API is represented by its sampled server entry point.

Main entry points: [`src/receipt_ocr/processors.py`](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/processors.py) (Receipt processor), [`src/receipt_ocr/providers.py`](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/providers.py) (LLM provider), [`app/server.py`](https://github.com/bhimrazy/receipt-ocr/blob/main/app/server.py) (Structured API), [`src/tesseract_ocr/utils.py`](https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/utils.py) (Receipt image OCR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_structured["Structured Extraction"]
  node_processor["Receipt processor<br/>[processors.py]"]
  node_provider["LLM provider<br/>[providers.py]"]
  node_prompts["Extraction prompts<br/>[prompts.py]"]
  node_image_encoding["Image encoding<br/>[utils.py]"]
  node_parser["Response parser<br/>[parsers.py]"]
  node_structured_result["Structured receipt data"]
end

subgraph group_tesseract["Raw OCR"]
  node_ocr_utils["Receipt image OCR<br/>[utils.py]"]
  node_raw_text["Raw receipt text"]
end

subgraph group_interfaces["User Interfaces"]
  node_llm_cli["Receipt CLI<br/>[cli.py]"]
  node_structured_api["Structured API<br/>[server.py]"]
  node_tesseract_cli["Tesseract CLI<br/>[main.py]"]
  node_tesseract_api["Tesseract API<br/>[app.py]"]
end

subgraph group_integrations["External Services"]
  node_llm_service{{"OpenAI-compatible LLM"}}
  node_tesseract_engine{{"Tesseract engine"}}
end

node_receipt_user(("Receipt user"))

node_receipt_user -->|"runs"| node_llm_cli
node_receipt_user -->|"uploads image"| node_structured_api
node_llm_cli -->|"processes receipt"| node_processor
node_structured_api -->|"processes receipt"| node_processor
node_processor -->|"requests extraction"| node_provider
node_provider -->|"encodes image"| node_image_encoding
node_provider -->|"uses prompts"| node_prompts
node_provider -->|"sends image and schema"| node_llm_service
node_llm_service -->|"returns completion"| node_provider
node_provider -->|"returns completion"| node_processor
node_processor -->|"parses response"| node_parser
node_parser -->|"produces"| node_structured_result
node_processor -->|"returns data"| node_llm_cli
node_processor -->|"returns data"| node_structured_api
node_structured_api -->|"responds with JSON"| node_receipt_user
node_receipt_user -->|"runs"| node_tesseract_cli
node_receipt_user -->|"uploads image"| node_tesseract_api
node_tesseract_cli -->|"recognizes text"| node_tesseract_engine
node_tesseract_cli -->|"prints"| node_raw_text
node_tesseract_api -->|"passes image bytes"| node_ocr_utils
node_ocr_utils -->|"recognizes text"| node_tesseract_engine
node_ocr_utils -->|"returns"| node_raw_text
node_tesseract_api -->|"responds with text"| node_receipt_user

click node_llm_cli "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/cli.py"
click node_structured_api "https://github.com/bhimrazy/receipt-ocr/blob/main/app/server.py"
click node_processor "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/processors.py"
click node_provider "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/providers.py"
click node_prompts "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/prompts.py"
click node_image_encoding "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/utils.py"
click node_parser "https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/parsers.py"
click node_tesseract_cli "https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/main.py"
click node_tesseract_api "https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/app.py"
click node_ocr_utils "https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/utils.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_processor,node_provider,node_prompts,node_image_encoding,node_parser,node_structured_result,node_receipt_user toneBlue
class node_ocr_utils,node_raw_text toneAmber
class node_llm_cli,node_structured_api,node_tesseract_cli,node_tesseract_api toneMint
class node_llm_service,node_tesseract_engine toneRose
```

## Components

### Structured Extraction

- [Receipt processor](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/processors.py): `src/receipt_ocr/processors.py`
- [LLM provider](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/providers.py): `src/receipt_ocr/providers.py`
- [Extraction prompts](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/prompts.py): `src/receipt_ocr/prompts.py`
- [Image encoding](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/utils.py): `src/receipt_ocr/utils.py`
- [Response parser](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/parsers.py): `src/receipt_ocr/parsers.py`
- **Structured receipt data**

### Raw OCR

- [Receipt image OCR](https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/utils.py): `src/tesseract_ocr/utils.py`
- **Raw receipt text**

### User Interfaces

- [Receipt CLI](https://github.com/bhimrazy/receipt-ocr/blob/main/src/receipt_ocr/cli.py): `src/receipt_ocr/cli.py`
- [Structured API](https://github.com/bhimrazy/receipt-ocr/blob/main/app/server.py): `app/server.py`
- [Tesseract CLI](https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/main.py): `src/tesseract_ocr/main.py`
- [Tesseract API](https://github.com/bhimrazy/receipt-ocr/blob/main/src/tesseract_ocr/app.py): `src/tesseract_ocr/app.py`

### External Services

- **OpenAI-compatible LLM**
- **Tesseract engine**

### Other components

- **Receipt user**

## Connections

- Receipt user → Receipt CLI: runs
- Receipt user → Structured API: uploads image
- Receipt CLI → Receipt processor: processes receipt
- Structured API → Receipt processor: processes receipt
- Receipt processor → LLM provider: requests extraction
- LLM provider → Image encoding: encodes image
- LLM provider → Extraction prompts: uses prompts
- LLM provider → OpenAI-compatible LLM: sends image and schema
- OpenAI-compatible LLM → LLM provider: returns completion
- LLM provider → Receipt processor: returns completion
- Receipt processor → Response parser: parses response
- Response parser → Structured receipt data: produces
- Receipt processor → Receipt CLI: returns data
- Receipt processor → Structured API: returns data
- Structured API → Receipt user: responds with JSON
- Receipt user → Tesseract CLI: runs
- Receipt user → Tesseract API: uploads image
- Tesseract CLI → Tesseract engine: recognizes text
- Tesseract CLI → Raw receipt text: prints
- Tesseract API → Receipt image OCR: passes image bytes
- Receipt image OCR → Tesseract engine: recognizes text
- Receipt image OCR → Raw receipt text: returns
- Tesseract API → Receipt user: responds with text