# aws-samples/amazon-textract-textractor architecture

> Architecture diagram of the GitHub repository aws-samples/amazon-textract-textractor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/amazon-textract-textractor
- Repository: https://github.com/aws-samples/amazon-textract-textractor

## Overview

Textractor is a Python interface to Amazon Textract: users submit documents for text, table, form, ID, receipt/expense, query, and layout extraction, then work with structured document entities or export/visualize them. Its core runtime wraps Textract calls, parses responses into entities, and exposes a CLI. The repository also includes companion caller, pretty-printing, overlay, geometry-finder, page-dimension, helper, and manifest packages. Relationships are limited to README statements and SOURCE INDEX references; some companion-package internals were not sampled.

Main entry points: [`textractor/parsers/response_parser.py`](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/parsers/response_parser.py) (Response parser), [`textractor/entities/document.py`](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/document.py) (Document), [`textractor/textractor.py`](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/textractor.py) (Textractor API), [`textractor/cli/cli.py`](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/cli/cli.py) (Command-line interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extraction runtime"]
  node_textractor["Textractor API<br/>[textractor.py]"]
  node_caller["Textract caller<br/>[t_call.py]"]
  node_parser["Response parser<br/>[response_parser.py]"]
  node_cli["Command-line interface<br/>[cli.py]"]
end

subgraph group_entities["Document model"]
  node_document["Document<br/>[document.py]"]
  node_page["Page entities<br/>[page.py]"]
  node_table["Tables<br/>[table.py]"]
  node_forms["Form entities<br/>[key_value.py]"]
  node_expense["Expense entities"]
  node_identity["Identity entities"]
  node_layout["Layout entities<br/>[layout.py]"]
  node_query["Query entities<br/>[query.py]"]
  node_geometry["Spatial geometry<br/>[bbox.py]"]
  node_linearization["Text linearization"]
end

subgraph group_outputs["Output tools"]
  node_visualizer["Entity visualization<br/>[entitylist.py]"]
  node_pretty["Pretty printing<br/>[t_pretty_print.py]"]
  node_expense_pretty["Expense printing"]
  node_overlay["Image overlays<br/>[t_overlay.py]"]
end

subgraph group_companions["Companion packages"]
  node_geo_finder["Geometry finder<br/>[tgeofinder.py]"]
  node_geo_words["Finder word model<br/>[tword.py]"]
  node_geo_db["OCR database<br/>[ocrdb.py]"]
  node_page_dimensions["Page dimensions"]
  node_manifest["Textract manifest<br/>[manifest.py]"]
  node_helper["Textract helper"]
end

node_user(("Document user"))
node_aws["Amazon Textract"]

node_user -->|"submits documents"| node_textractor
node_textractor -->|"calls APIs"| node_caller
node_caller -->|"requests extraction"| node_aws
node_textractor -->|"parses responses"| node_parser
node_parser -->|"builds document"| node_document
node_parser -->|"builds pages"| node_page
node_parser -->|"builds tables"| node_table
node_parser -->|"builds key values"| node_forms
node_parser -->|"builds expense data"| node_expense
node_parser -->|"builds identity data"| node_identity
node_parser -->|"builds query results"| node_query
node_parser -->|"builds layout data"| node_layout
node_page -->|"uses bounding boxes"| node_geometry
node_document -->|"contains pages"| node_page
node_document -->|"exposes visualization"| node_visualizer
node_visualizer -->|"positions entities"| node_geometry
node_document -->|"linearizes text"| node_linearization
node_user -->|"runs commands"| node_cli
node_cli -->|"invokes extraction"| node_textractor
node_cli -->|"supports overlays"| node_visualizer
node_user -->|"exports output"| node_pretty
node_user -.->|"prints expenses"| node_expense_pretty
node_user -->|"draws entities"| node_overlay
node_user -->|"finds information"| node_geo_finder
node_geo_finder -->|"uses word model"| node_geo_words
node_geo_finder -->|"uses OCR database"| node_geo_db
node_user -.->|"uses page sizing"| node_page_dimensions
node_user -.->|"uses manifest tools"| node_manifest
node_user -.->|"uses helper package"| node_helper

click node_textractor "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/textractor.py"
click node_caller "https://github.com/aws-samples/amazon-textract-textractor/blob/master/caller/textractcaller/t_call.py"
click node_parser "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/parsers/response_parser.py"
click node_cli "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/cli/cli.py"
click node_document "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/document.py"
click node_page "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/page.py"
click node_table "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/table.py"
click node_forms "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/key_value.py"
click node_expense "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/expense_document.py"
click node_identity "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/identity_document.py"
click node_layout "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/layout.py"
click node_query "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/query.py"
click node_geometry "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/bbox.py"
click node_linearization "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/data/text_linearization_config.py"
click node_visualizer "https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/visualizers/entitylist.py"
click node_pretty "https://github.com/aws-samples/amazon-textract-textractor/blob/master/prettyprinter/textractprettyprinter/t_pretty_print.py"
click node_expense_pretty "https://github.com/aws-samples/amazon-textract-textractor/blob/master/prettyprinter/textractprettyprinter/t_pretty_print_expense.py"
click node_overlay "https://github.com/aws-samples/amazon-textract-textractor/blob/master/overlayer/textractoverlayer/t_overlay.py"
click node_geo_finder "https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/tgeofinder.py"
click node_geo_words "https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/tword.py"
click node_geo_db "https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/ocrdb.py"
click node_page_dimensions "https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinepagedimensions/textractpagedimensions/t_pagedimensions.py"
click node_manifest "https://github.com/aws-samples/amazon-textract-textractor/blob/master/idp_cdk_manifest/textractmanifest/manifest.py"
click node_helper "https://github.com/aws-samples/amazon-textract-textractor/tree/master/helper/textracthelper"

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_textractor,node_caller,node_parser,node_cli,node_user toneBlue
class node_document,node_page,node_table,node_forms,node_expense,node_identity,node_layout,node_query,node_geometry,node_linearization toneAmber
class node_visualizer,node_pretty,node_expense_pretty,node_overlay toneMint
class node_geo_finder,node_geo_words,node_geo_db,node_page_dimensions,node_manifest,node_helper toneRose
class node_aws toneIndigo
```

## Components

### Extraction runtime

- [Textractor API](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/textractor.py): `textractor/textractor.py`
- [Textract caller](https://github.com/aws-samples/amazon-textract-textractor/blob/master/caller/textractcaller/t_call.py): `caller/textractcaller/t_call.py`
- [Response parser](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/parsers/response_parser.py): `textractor/parsers/response_parser.py`
- [Command-line interface](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/cli/cli.py): `textractor/cli/cli.py`

### Document model

- [Document](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/document.py): `textractor/entities/document.py`
- [Page entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/page.py): `textractor/entities/page.py`
- [Tables](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/table.py): `textractor/entities/table.py`
- [Form entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/key_value.py): `textractor/entities/key_value.py`
- [Expense entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/expense_document.py): `textractor/entities/expense_document.py`
- [Identity entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/identity_document.py): `textractor/entities/identity_document.py`
- [Layout entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/layout.py): `textractor/entities/layout.py`
- [Query entities](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/query.py): `textractor/entities/query.py`
- [Spatial geometry](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/entities/bbox.py): `textractor/entities/bbox.py`
- [Text linearization](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/data/text_linearization_config.py): `textractor/data/text_linearization_config.py`

### Output tools

- [Entity visualization](https://github.com/aws-samples/amazon-textract-textractor/blob/master/textractor/visualizers/entitylist.py): `textractor/visualizers/entitylist.py`
- [Pretty printing](https://github.com/aws-samples/amazon-textract-textractor/blob/master/prettyprinter/textractprettyprinter/t_pretty_print.py): `prettyprinter/textractprettyprinter/t_pretty_print.py`
- [Expense printing](https://github.com/aws-samples/amazon-textract-textractor/blob/master/prettyprinter/textractprettyprinter/t_pretty_print_expense.py): `prettyprinter/textractprettyprinter/t_pretty_print_expense.py`
- [Image overlays](https://github.com/aws-samples/amazon-textract-textractor/blob/master/overlayer/textractoverlayer/t_overlay.py): `overlayer/textractoverlayer/t_overlay.py`

### Companion packages

- [Geometry finder](https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/tgeofinder.py): `tpipelinegeofinder/textractgeofinder/tgeofinder.py`
- [Finder word model](https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/tword.py): `tpipelinegeofinder/textractgeofinder/tword.py`
- [OCR database](https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinegeofinder/textractgeofinder/ocrdb.py): `tpipelinegeofinder/textractgeofinder/ocrdb.py`
- [Page dimensions](https://github.com/aws-samples/amazon-textract-textractor/blob/master/tpipelinepagedimensions/textractpagedimensions/t_pagedimensions.py): `tpipelinepagedimensions/textractpagedimensions/t_pagedimensions.py`
- [Textract manifest](https://github.com/aws-samples/amazon-textract-textractor/blob/master/idp_cdk_manifest/textractmanifest/manifest.py): `idp_cdk_manifest/textractmanifest/manifest.py`
- [Textract helper](https://github.com/aws-samples/amazon-textract-textractor/tree/master/helper/textracthelper): `helper/textracthelper`

### Other components

- **Document user**
- **Amazon Textract**

## Connections

- Document user → Textractor API: submits documents (evidence: `README.md`)
- Textractor API → Textract caller: calls APIs (evidence: `textractor/textractor.py`)
- Textract caller → Amazon Textract: requests extraction (evidence: `README.md`)
- Textractor API → Response parser: parses responses (evidence: `textractor/textractor.py`)
- Response parser → Document: builds document (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Page entities: builds pages (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Tables: builds tables (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Form entities: builds key values (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Expense entities: builds expense data (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Identity entities: builds identity data (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Query entities: builds query results (evidence: `textractor/parsers/response_parser.py`)
- Response parser → Layout entities: builds layout data (evidence: `textractor/parsers/response_parser.py`)
- Page entities → Spatial geometry: uses bounding boxes (evidence: `textractor/entities/page.py`)
- Document → Page entities: contains pages (evidence: `textractor/entities/document.py`)
- Document → Entity visualization: exposes visualization (evidence: `textractor/entities/document.py`)
- Entity visualization → Spatial geometry: positions entities (evidence: `textractor/visualizers/entitylist.py`)
- Document → Text linearization: linearizes text (evidence: `textractor/entities/document.py`)
- Document user → Command-line interface: runs commands (evidence: `README.md`)
- Command-line interface → Textractor API: invokes extraction (evidence: `textractor/cli/cli.py`)
- Command-line interface → Entity visualization: supports overlays (evidence: `textractor/cli/cli.py`)
- Document user → Pretty printing: exports output (evidence: `README.md`)
- Document user → Expense printing: prints expenses (evidence: `README.md`)
- Document user → Image overlays: draws entities (evidence: `README.md`)
- Document user → Geometry finder: finds information (evidence: `README.md`)
- Geometry finder → Finder word model: uses word model (evidence: `tpipelinegeofinder/textractgeofinder/tgeofinder.py`)
- Geometry finder → OCR database: uses OCR database (evidence: `tpipelinegeofinder/textractgeofinder/tgeofinder.py`)
- Document user → Page dimensions: uses page sizing
- Document user → Textract manifest: uses manifest tools
- Document user → Textract helper: uses helper package