# rsommerfeld/trocr architecture

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

- Interactive diagram: https://gitdiagram.com/rsommerfeld/trocr
- Repository: https://github.com/rsommerfeld/trocr

## Overview

This repository is a small TrOCR-based handwritten-character recognition application. Its user workflow starts at the CLI (or the exported predictor interface), loads a processor and model, prepares images, then predicts text and confidence, validates predictions against labels, or trains and saves a model. The graph also preserves dataset preparation, shared run context, and configurable paths and training parameters. Edges reflect the shown calls and documented modes; the configured checkpoint directory and Hugging Face model source are runtime locations, not source files in the tree.

Main entry points: [`src/main.py`](https://github.com/rsommerfeld/trocr/blob/main/src/main.py) (Workflow setup), [`src/dataset.py`](https://github.com/rsommerfeld/trocr/blob/main/src/dataset.py) (Labeled image dataset), [`src/util.py`](https://github.com/rsommerfeld/trocr/blob/main/src/util.py) (Model and processor loading), [`src/scripts.py`](https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_predictor["Predictor API<br/>[main.py]"]
end

subgraph group_data["Datasets and labels"]
  node_hcr_dataset["Labeled image dataset<br/>[dataset.py]"]
  node_memory_dataset["In-memory images<br/>[dataset.py]"]
  node_training_data["Training images"]
  node_validation_data["Validation images"]
  node_labels["Image labels CSV<br/>[labels.csv]"]
end

subgraph group_runtime["Recognition workflows"]
  node_orchestrator["Workflow setup<br/>[main.py]"]
  node_context["Training context<br/>[context.py]"]
  node_prediction["Prediction and confidence<br/>[scripts.py]"]
  node_validation["Validation scoring<br/>[scripts.py]"]
  node_training["Model training<br/>[scripts.py]"]
end

subgraph group_configuration["Configuration and models"]
  node_model_setup["Model and processor loading<br/>[util.py]"]
  node_paths["Data and checkpoint paths<br/>[paths.py]"]
  node_settings["Training settings<br/>[constants.py]"]
  node_checkpoint["Local model checkpoint"]
end

node_user(("User"))
node_huggingface["Hugging Face models"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches workflows"| node_orchestrator
node_user -->|"calls API"| node_predictor
node_orchestrator -->|"loads models"| node_model_setup
node_orchestrator -->|"creates datasets"| node_hcr_dataset
node_orchestrator -->|"prepares images"| node_memory_dataset
node_orchestrator -->|"assembles context"| node_context
node_orchestrator -->|"starts training"| node_training
node_orchestrator -->|"starts validation"| node_validation
node_orchestrator -->|"predicts images"| node_prediction
node_orchestrator -->|"saves model"| node_checkpoint
node_hcr_dataset -->|"reads images"| node_training_data
node_hcr_dataset -->|"reads images"| node_validation_data
node_hcr_dataset -->|"loads labels"| node_labels
node_validation -->|"uses validation data"| node_context
node_validation -->|"requests predictions"| node_prediction
node_training -->|"uses training data"| node_context
node_training -->|"scores epochs"| node_validation
node_model_setup -->|"reads model paths"| node_paths
node_model_setup -->|"selects device"| node_settings
node_model_setup -->|"loads local model"| node_checkpoint
node_model_setup -->|"loads pretrained model"| node_huggingface
node_hcr_dataset -->|"uses data paths"| node_paths
node_hcr_dataset -->|"uses padding settings"| node_settings
node_prediction -->|"uses device"| node_settings
node_training -->|"uses training parameters"| node_settings
node_predictor -->|"builds image batches"| node_memory_dataset
node_predictor -->|"requests predictions"| node_prediction
node_predictor -->|"loads processor and model"| node_model_setup

click node_cli "https://github.com/rsommerfeld/trocr/blob/main/src/cli.py"
click node_predictor "https://github.com/rsommerfeld/trocr/blob/main/src/main.py"
click node_orchestrator "https://github.com/rsommerfeld/trocr/blob/main/src/main.py"
click node_hcr_dataset "https://github.com/rsommerfeld/trocr/blob/main/src/dataset.py"
click node_memory_dataset "https://github.com/rsommerfeld/trocr/blob/main/src/dataset.py"
click node_training_data "https://github.com/rsommerfeld/trocr/tree/main/train"
click node_validation_data "https://github.com/rsommerfeld/trocr/tree/main/val"
click node_labels "https://github.com/rsommerfeld/trocr/blob/main/gt/labels.csv"
click node_context "https://github.com/rsommerfeld/trocr/blob/main/src/context.py"
click node_prediction "https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py"
click node_validation "https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py"
click node_training "https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py"
click node_model_setup "https://github.com/rsommerfeld/trocr/blob/main/src/util.py"
click node_paths "https://github.com/rsommerfeld/trocr/blob/main/src/configs/paths.py"
click node_settings "https://github.com/rsommerfeld/trocr/blob/main/src/configs/constants.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_predictor,node_user toneBlue
class node_hcr_dataset,node_memory_dataset,node_training_data,node_validation_data,node_labels toneAmber
class node_orchestrator,node_context,node_prediction,node_validation,node_training toneMint
class node_model_setup,node_paths,node_settings,node_checkpoint toneRose
class node_huggingface toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/rsommerfeld/trocr/blob/main/src/cli.py): `src/cli.py`
- [Predictor API](https://github.com/rsommerfeld/trocr/blob/main/src/main.py): `src/main.py`

### Datasets and labels

- [Labeled image dataset](https://github.com/rsommerfeld/trocr/blob/main/src/dataset.py): `src/dataset.py`
- [In-memory images](https://github.com/rsommerfeld/trocr/blob/main/src/dataset.py): `src/dataset.py`
- [Training images](https://github.com/rsommerfeld/trocr/tree/main/train): `train`
- [Validation images](https://github.com/rsommerfeld/trocr/tree/main/val): `val`
- [Image labels CSV](https://github.com/rsommerfeld/trocr/blob/main/gt/labels.csv): `gt/labels.csv`

### Recognition workflows

- [Workflow setup](https://github.com/rsommerfeld/trocr/blob/main/src/main.py): `src/main.py`
- [Training context](https://github.com/rsommerfeld/trocr/blob/main/src/context.py): `src/context.py`
- [Prediction and confidence](https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py): `src/scripts.py`
- [Validation scoring](https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py): `src/scripts.py`
- [Model training](https://github.com/rsommerfeld/trocr/blob/main/src/scripts.py): `src/scripts.py`

### Configuration and models

- [Model and processor loading](https://github.com/rsommerfeld/trocr/blob/main/src/util.py): `src/util.py`
- [Data and checkpoint paths](https://github.com/rsommerfeld/trocr/blob/main/src/configs/paths.py): `src/configs/paths.py`
- [Training settings](https://github.com/rsommerfeld/trocr/blob/main/src/configs/constants.py): `src/configs/constants.py`
- **Local model checkpoint**

### Other components

- **User**
- **Hugging Face models**

## Connections

- User → CLI commands: runs commands
- CLI commands → Workflow setup: dispatches workflows (evidence: `src/cli.py`)
- User → Predictor API: calls API (evidence: `README.md`)
- Workflow setup → Model and processor loading: loads models (evidence: `src/main.py`)
- Workflow setup → Labeled image dataset: creates datasets (evidence: `src/main.py`)
- Workflow setup → In-memory images: prepares images (evidence: `src/main.py`)
- Workflow setup → Training context: assembles context (evidence: `src/main.py`)
- Workflow setup → Model training: starts training (evidence: `src/main.py`)
- Workflow setup → Validation scoring: starts validation (evidence: `src/main.py`)
- Workflow setup → Prediction and confidence: predicts images (evidence: `src/main.py`)
- Workflow setup → Local model checkpoint: saves model (evidence: `src/main.py`)
- Labeled image dataset → Training images: reads images (evidence: `src/dataset.py`)
- Labeled image dataset → Validation images: reads images (evidence: `src/dataset.py`)
- Labeled image dataset → Image labels CSV: loads labels (evidence: `src/dataset.py`)
- Validation scoring → Training context: uses validation data (evidence: `src/scripts.py`)
- Validation scoring → Prediction and confidence: requests predictions (evidence: `src/scripts.py`)
- Model training → Training context: uses training data (evidence: `src/scripts.py`)
- Model training → Validation scoring: scores epochs (evidence: `src/scripts.py`)
- Model and processor loading → Data and checkpoint paths: reads model paths (evidence: `src/util.py`)
- Model and processor loading → Training settings: selects device (evidence: `src/util.py`)
- Model and processor loading → Local model checkpoint: loads local model (evidence: `src/util.py`)
- Model and processor loading → Hugging Face models: loads pretrained model (evidence: `src/util.py`)
- Labeled image dataset → Data and checkpoint paths: uses data paths (evidence: `src/dataset.py`)
- Labeled image dataset → Training settings: uses padding settings (evidence: `src/dataset.py`)
- Prediction and confidence → Training settings: uses device (evidence: `src/scripts.py`)
- Model training → Training settings: uses training parameters (evidence: `src/scripts.py`)
- Predictor API → In-memory images: builds image batches (evidence: `src/main.py`)
- Predictor API → Prediction and confidence: requests predictions (evidence: `src/main.py`)
- Predictor API → Model and processor loading: loads processor and model (evidence: `src/main.py`)
