# simeonkolchin/invoice-ocr-framework architecture

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

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

## Overview

Invoice OCR Framework turns supplier PDFs into structured invoice records using supplier-specific JSON templates. The main flow loads templates, OCRs and matches an invoice, extracts configured fields, applies supplier-specific logic and normalizes values. The README also documents table extraction, XML output, and email-to-Drive processing; some of those connections are not visible in the sampled calls, so they are shown only where documented or marked unverified.

Main entry points: [`core/invoice_parser.py`](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_parser.py) (Invoice orchestrator), [`utils/utils.py`](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py) (Email intake), [`main.py`](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/main.py) (PDF CLI), [`templates/valle_flores/valle_flores.py`](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/templates/valle_flores/valle_flores.py) (Supplier custom logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and intake"]
  node_cli["PDF CLI<br/>[main.py]"]
  node_email_intake["Email intake<br/>[utils.py]"]
end

subgraph group_templates["Template system"]
  node_template_loader["Template loader<br/>[utils.py]"]
  node_supplier_configs["Supplier configs"]
  node_template_match["Template matching"]
end

subgraph group_extraction["OCR and extraction"]
  node_invoice_parser["Invoice orchestrator<br/>[invoice_parser.py]"]
  node_pdf_ocr["PDF OCR"]
  node_fulltext_parser["Full-text parser"]
  node_split_parser["Split-region parser"]
  node_static_parser["Static fields<br/>[static_parser.py]"]
  node_table_parser["Table extraction<br/>[table_parser.py]"]
  node_parser_base["Parser base<br/>[base_parser.py]"]
  node_supplier_logic["Supplier custom logic<br/>[valle_flores.py]"]
  node_table_helpers["Table helpers<br/>[table_functions.py]"]
end

subgraph group_results["Normalization and output"]
  node_normalizer["Field normalization<br/>[invoice_parser.py]"]
  node_reference_dicts["Name dictionaries<br/>[translate.py]"]
  node_xml_output["XML output<br/>[utils.py]"]
  node_record["Structured record"]
end

node_pdf_user(("PDF submitter"))
node_mail_services["Mail and Drive"]

node_pdf_user -->|"submits PDF"| node_cli
node_cli -->|"loads templates"| node_template_loader
node_cli -->|"parses PDF"| node_invoice_parser
node_template_loader -->|"loads configs"| node_supplier_configs
node_template_loader -->|"creates templates"| node_template_match
node_invoice_parser -->|"OCRs first page"| node_pdf_ocr
node_invoice_parser -->|"tests keywords"| node_template_match
node_invoice_parser -->|"dispatches fields"| node_fulltext_parser
node_invoice_parser -->|"dispatches fields"| node_split_parser
node_invoice_parser -->|"dispatches fields"| node_static_parser
node_fulltext_parser -->|"inherits"| node_parser_base
node_split_parser -->|"inherits"| node_parser_base
node_static_parser -->|"inherits"| node_parser_base
node_template_match -.->|"loads custom module"| node_supplier_logic
node_supplier_logic -->|"returns custom fields"| node_invoice_parser
node_supplier_logic -.->|"extracts tables"| node_table_helpers
node_invoice_parser -.->|"supports table strategy"| node_table_parser
node_invoice_parser -->|"fills and corrects"| node_normalizer
node_normalizer -->|"looks up names"| node_reference_dicts
node_normalizer -->|"produces record"| node_record
node_email_intake -.->|"polls mailbox"| node_mail_services
node_email_intake -.->|"reuses pipeline"| node_invoice_parser
node_email_intake -.->|"writes XML"| node_xml_output
node_xml_output -.->|"uploads result"| node_mail_services

click node_cli "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/main.py"
click node_email_intake "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py"
click node_template_loader "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py"
click node_supplier_configs "https://github.com/simeonkolchin/invoice-ocr-framework/tree/main/templates"
click node_template_match "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_template.py"
click node_invoice_parser "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_parser.py"
click node_fulltext_parser "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/tesseract_parser.py"
click node_split_parser "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/tesseract_split_parser.py"
click node_static_parser "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/static_parser.py"
click node_table_parser "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/table_parser.py"
click node_parser_base "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/base_parser.py"
click node_supplier_logic "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/templates/valle_flores/valle_flores.py"
click node_table_helpers "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/table_functions.py"
click node_normalizer "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_parser.py"
click node_reference_dicts "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/translate.py"
click node_xml_output "https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/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_cli,node_email_intake toneBlue
class node_template_loader,node_supplier_configs,node_template_match toneAmber
class node_invoice_parser,node_pdf_ocr,node_fulltext_parser,node_split_parser,node_static_parser,node_table_parser,node_parser_base,node_supplier_logic,node_table_helpers toneMint
class node_normalizer,node_reference_dicts,node_xml_output,node_record toneRose
class node_pdf_user,node_mail_services toneIndigo
```

## Components

### Entry and intake

- [PDF CLI](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/main.py): `main.py`
- [Email intake](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py): `utils/utils.py`

### Template system

- [Template loader](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py): `utils/utils.py`
- [Supplier configs](https://github.com/simeonkolchin/invoice-ocr-framework/tree/main/templates): `templates`
- [Template matching](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_template.py): `core/invoice_template.py`

### OCR and extraction

- [Invoice orchestrator](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_parser.py): `core/invoice_parser.py`
- **PDF OCR**
- [Full-text parser](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/tesseract_parser.py): `parsers/tesseract_parser.py`
- [Split-region parser](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/tesseract_split_parser.py): `parsers/tesseract_split_parser.py`
- [Static fields](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/static_parser.py): `parsers/static_parser.py`
- [Table extraction](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/table_parser.py): `parsers/table_parser.py`
- [Parser base](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/parsers/base_parser.py): `parsers/base_parser.py`
- [Supplier custom logic](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/templates/valle_flores/valle_flores.py): `templates/valle_flores/valle_flores.py`
- [Table helpers](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/table_functions.py): `utils/table_functions.py`

### Normalization and output

- [Field normalization](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/core/invoice_parser.py): `core/invoice_parser.py`
- [Name dictionaries](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/translate.py): `utils/translate.py`
- [XML output](https://github.com/simeonkolchin/invoice-ocr-framework/blob/main/utils/utils.py): `utils/utils.py`
- **Structured record**

### Other components

- **PDF submitter**
- **Mail and Drive**

## Connections

- PDF submitter → PDF CLI: submits PDF (evidence: `main.py`)
- PDF CLI → Template loader: loads templates (evidence: `main.py`)
- PDF CLI → Invoice orchestrator: parses PDF (evidence: `main.py`)
- Template loader → Supplier configs: loads configs (evidence: `utils/utils.py`)
- Template loader → Template matching: creates templates (evidence: `utils/utils.py`)
- Invoice orchestrator → PDF OCR: OCRs first page (evidence: `core/invoice_parser.py`)
- Invoice orchestrator → Template matching: tests keywords (evidence: `README.md`)
- Invoice orchestrator → Full-text parser: dispatches fields (evidence: `core/invoice_parser.py`)
- Invoice orchestrator → Split-region parser: dispatches fields (evidence: `core/invoice_parser.py`)
- Invoice orchestrator → Static fields: dispatches fields (evidence: `core/invoice_parser.py`)
- Full-text parser → Parser base: inherits (evidence: `parsers/tesseract_parser.py`)
- Split-region parser → Parser base: inherits (evidence: `parsers/tesseract_split_parser.py`)
- Static fields → Parser base: inherits (evidence: `parsers/static_parser.py`)
- Template matching → Supplier custom logic: loads custom module (evidence: `README.md`)
- Supplier custom logic → Invoice orchestrator: returns custom fields (evidence: `core/invoice_parser.py`)
- Supplier custom logic → Table helpers: extracts tables
- Invoice orchestrator → Table extraction: supports table strategy (evidence: `README.md`)
- Invoice orchestrator → Field normalization: fills and corrects (evidence: `core/invoice_parser.py`)
- Field normalization → Name dictionaries: looks up names (evidence: `core/invoice_parser.py`)
- Field normalization → Structured record: produces record (evidence: `README.md`)
- Email intake → Mail and Drive: polls mailbox (evidence: `README.md`)
- Email intake → Invoice orchestrator: reuses pipeline
- Email intake → XML output: writes XML (evidence: `README.md`)
- XML output → Mail and Drive: uploads result (evidence: `README.md`)
