# codebywiam/invoice-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/codebywiam/invoice-ocr
- Repository: https://github.com/codebywiam/invoice-ocr

## Overview

This is an invoice/receipt OCR application with both a Streamlit interface and a headless-capable CLI. Users provide PDFs; the entry point converts pages to images, preprocesses them, runs Tesseract, extracts invoice fields, and presents or exports the structured results. The Streamlit path additionally supports field correction, bounding-box previews, and combined CSV download; the CLI saves visualizations and a summary CSV. The workflow is evidenced by README and sampled entry points; supporting module internals were not sampled, so their detailed behavior is summarized from documentation.

Main entry points: [`app/app.py`](https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py) (Streamlit app), [`main.py`](https://github.com/codebywiam/invoice-ocr/blob/master/main.py) (CLI pipeline), [`src/pdf_converter.py`](https://github.com/codebywiam/invoice-ocr/blob/master/src/pdf_converter.py) (PDF converter), [`src/ocr_engine.py`](https://github.com/codebywiam/invoice-ocr/blob/master/src/ocr_engine.py) (OCR engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_cli["CLI pipeline<br/>[main.py]"]
end

subgraph group_processing["OCR processing"]
  node_converter["PDF converter<br/>[pdf_converter.py]"]
  node_poppler["Poppler<br/>[poppler-24.08.0]"]
  node_images["Page images"]
  node_preprocess["Image preprocessing<br/>[preprocess.py]"]
  node_tesseract["Tesseract OCR"]
  node_ocr["OCR engine<br/>[ocr_engine.py]"]
  node_fields["Field extraction<br/>[extractor.py]"]
end

subgraph group_results["Review and export"]
  node_visualizer["Box visualizer<br/>[visualize.py]"]
  node_review["Field review<br/>[app.py]"]
  node_dataframe["Combined results<br/>[app.py]"]
  node_csv["CSV export<br/>[app.py]"]
  node_cli_csv["Summary CSV<br/>[main.py]"]
end

node_user(("Invoice user"))
node_pdfs["Invoice PDFs"]

node_user -->|"uploads PDFs"| node_streamlit
node_pdfs -->|"reads PDFs"| node_streamlit
node_streamlit -->|"converts pages"| node_converter
node_cli -->|"converts PDFs"| node_converter
node_converter -->|"uses"| node_poppler
node_converter -->|"writes pages"| node_images
node_streamlit -->|"preprocesses pages"| node_preprocess
node_cli -->|"preprocesses pages"| node_preprocess
node_preprocess -->|"supplies images"| node_ocr
node_ocr -->|"runs OCR"| node_tesseract
node_streamlit -->|"runs and reads OCR"| node_ocr
node_cli -->|"runs and reads OCR"| node_ocr
node_streamlit -->|"extracts fields"| node_fields
node_cli -->|"extracts fields"| node_fields
node_streamlit -->|"draws OCR boxes"| node_visualizer
node_cli -->|"draws OCR boxes"| node_visualizer
node_fields -->|"provides fields"| node_review
node_user -->|"corrects fields"| node_review
node_review -->|"aggregates records"| node_dataframe
node_dataframe -->|"downloads CSV"| node_csv
node_cli -->|"writes summary"| node_cli_csv

click node_streamlit "https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py"
click node_cli "https://github.com/codebywiam/invoice-ocr/blob/master/main.py"
click node_converter "https://github.com/codebywiam/invoice-ocr/blob/master/src/pdf_converter.py"
click node_poppler "https://github.com/codebywiam/invoice-ocr/tree/master/poppler-24.08.0"
click node_preprocess "https://github.com/codebywiam/invoice-ocr/blob/master/src/preprocess.py"
click node_ocr "https://github.com/codebywiam/invoice-ocr/blob/master/src/ocr_engine.py"
click node_fields "https://github.com/codebywiam/invoice-ocr/blob/master/src/extractor.py"
click node_visualizer "https://github.com/codebywiam/invoice-ocr/blob/master/src/visualize.py"
click node_review "https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py"
click node_dataframe "https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py"
click node_csv "https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py"
click node_cli_csv "https://github.com/codebywiam/invoice-ocr/blob/master/main.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_streamlit,node_cli,node_user toneBlue
class node_converter,node_poppler,node_images,node_preprocess,node_tesseract,node_ocr,node_fields toneAmber
class node_visualizer,node_review,node_dataframe,node_csv,node_cli_csv toneMint
class node_pdfs toneIndigo
```

## Components

### Entry points

- [Streamlit app](https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py): `app/app.py`
- [CLI pipeline](https://github.com/codebywiam/invoice-ocr/blob/master/main.py): `main.py`

### OCR processing

- [PDF converter](https://github.com/codebywiam/invoice-ocr/blob/master/src/pdf_converter.py): `src/pdf_converter.py`
- [Poppler](https://github.com/codebywiam/invoice-ocr/tree/master/poppler-24.08.0): `poppler-24.08.0`
- **Page images**
- [Image preprocessing](https://github.com/codebywiam/invoice-ocr/blob/master/src/preprocess.py): `src/preprocess.py`
- **Tesseract OCR**
- [OCR engine](https://github.com/codebywiam/invoice-ocr/blob/master/src/ocr_engine.py): `src/ocr_engine.py`
- [Field extraction](https://github.com/codebywiam/invoice-ocr/blob/master/src/extractor.py): `src/extractor.py`

### Review and export

- [Box visualizer](https://github.com/codebywiam/invoice-ocr/blob/master/src/visualize.py): `src/visualize.py`
- [Field review](https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py): `app/app.py`
- [Combined results](https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py): `app/app.py`
- [CSV export](https://github.com/codebywiam/invoice-ocr/blob/master/app/app.py): `app/app.py`
- [Summary CSV](https://github.com/codebywiam/invoice-ocr/blob/master/main.py): `main.py`

### Other components

- **Invoice user**
- **Invoice PDFs**

## Connections

- Invoice user → Streamlit app: uploads PDFs
- Invoice PDFs → Streamlit app: reads PDFs
- Streamlit app → PDF converter: converts pages
- CLI pipeline → PDF converter: converts PDFs
- PDF converter → Poppler: uses
- PDF converter → Page images: writes pages
- Streamlit app → Image preprocessing: preprocesses pages
- CLI pipeline → Image preprocessing: preprocesses pages
- Image preprocessing → OCR engine: supplies images
- OCR engine → Tesseract OCR: runs OCR
- Streamlit app → OCR engine: runs and reads OCR
- CLI pipeline → OCR engine: runs and reads OCR
- Streamlit app → Field extraction: extracts fields
- CLI pipeline → Field extraction: extracts fields
- Streamlit app → Box visualizer: draws OCR boxes
- CLI pipeline → Box visualizer: draws OCR boxes
- Field extraction → Field review: provides fields
- Invoice user → Field review: corrects fields
- Field review → Combined results: aggregates records
- Combined results → CSV export: downloads CSV
- CLI pipeline → Summary CSV: writes summary