# sadeghi-sara/zipvan architecture

> Architecture diagram of the GitHub repository sadeghi-sara/zipvan, 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/sadeghi-sara/zipvan
- Repository: https://github.com/sadeghi-sara/zipvan

## Overview

ZipVAN trains handwritten line recognizers with CTC and consistency regularization, then initializes paragraph recognition from a trained line model. Its user-facing workflow also formats IAM data and evaluates predictions. The graph includes the shared dataset, model, and training infrastructure plus optimizer and preset configuration. Source evidence is partial: unsampled implementation details are omitted, while documented workflow links use the README.

Main entry points: [`OCR/document_OCR/v_attention/main_pg_va.py`](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/main_pg_va.py) (Paragraph run and evaluation), [`OCR/line_OCR/ctc/main_line_ctc.py`](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/main_line_ctc.py) (Line run and evaluation), [`basic/generic_dataset_manager.py`](https://github.com/sadeghi-sara/zipvan/blob/master/basic/generic_dataset_manager.py) (Dataset manager), [`OCR/line_OCR/ctc/trainer_line_ctc.py`](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/trainer_line_ctc.py) (Line CTC trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_formatter["IAM formatter<br/>[format_datasets.py]"]
end

subgraph group_line["Line recognition"]
  node_line_main["Line run and evaluation<br/>[main_line_ctc.py]"]
  node_line_model["Line CTC models<br/>[models_line_ctc.py]"]
  node_line_trainer["Line CTC trainer"]
end

subgraph group_paragraph["Paragraph recognition"]
  node_paragraph_main["Paragraph run and evaluation<br/>[main_pg_va.py]"]
  node_paragraph_model["Vertical attention model<br/>[models_pg_va.py]"]
  node_paragraph_trainer["Paragraph trainer<br/>[trainer_pg_va.py]"]
end

subgraph group_shared["Shared training core"]
  node_dataset["Dataset manager"]
  node_transforms["Image transforms<br/>[transforms.py]"]
  node_training["Training manager"]
  node_base_models["Encoder building blocks<br/>[models.py]"]
  node_presets["Training presets<br/>[presets.py]"]
  node_optimizer["ScaledAdam and Eden"]
  node_scaling["Scaling layers<br/>[scaling.py]"]
  node_logger["Training logger<br/>[train_logger.py]"]
  node_metrics["OCR metrics<br/>[utils.py]"]
end

node_user(("Researcher"))
node_iam[("IAM dataset")]

node_user -->|"formats data"| node_formatter
node_iam -->|"provides source"| node_formatter
node_formatter -->|"writes formatted data"| node_dataset
node_user -->|"starts line run"| node_line_main
node_line_main -->|"creates trainer"| node_line_trainer
node_line_main -->|"configures model"| node_line_model
node_line_main -->|"configures datasets"| node_dataset
node_line_main -->|"selects preset"| node_presets
node_line_trainer -->|"inherits training"| node_training
node_line_trainer -->|"runs encoder and decoder"| node_line_model
node_line_trainer -->|"uses OCR metrics"| node_metrics
node_user -->|"starts paragraph run"| node_paragraph_main
node_paragraph_main -->|"creates trainer"| node_paragraph_trainer
node_paragraph_main -->|"configures model"| node_paragraph_model
node_paragraph_main -->|"configures datasets"| node_dataset
node_paragraph_main -->|"selects preset"| node_presets
node_paragraph_main -->|"loads line checkpoint"| node_line_main
node_paragraph_trainer -->|"inherits training"| node_training
node_paragraph_trainer -->|"runs attention decoder"| node_paragraph_model
node_dataset -->|"uses transforms"| node_transforms
node_training -->|"uses datasets"| node_dataset
node_training -->|"logs training"| node_logger
node_presets -->|"configures optimizer"| node_optimizer
node_base_models -->|"uses scaling"| node_scaling

click node_formatter "https://github.com/sadeghi-sara/zipvan/blob/master/Datasets/format_datasets.py"
click node_dataset "https://github.com/sadeghi-sara/zipvan/blob/master/basic/generic_dataset_manager.py"
click node_transforms "https://github.com/sadeghi-sara/zipvan/blob/master/basic/transforms.py"
click node_line_main "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/main_line_ctc.py"
click node_line_model "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/models_line_ctc.py"
click node_line_trainer "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/trainer_line_ctc.py"
click node_paragraph_main "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/main_pg_va.py"
click node_paragraph_model "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/models_pg_va.py"
click node_paragraph_trainer "https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/trainer_pg_va.py"
click node_training "https://github.com/sadeghi-sara/zipvan/blob/master/basic/generic_training_manager.py"
click node_base_models "https://github.com/sadeghi-sara/zipvan/blob/master/basic/models.py"
click node_presets "https://github.com/sadeghi-sara/zipvan/blob/master/basic/presets.py"
click node_optimizer "https://github.com/sadeghi-sara/zipvan/blob/master/basic/scaled_optimizer.py"
click node_scaling "https://github.com/sadeghi-sara/zipvan/blob/master/basic/scaling.py"
click node_logger "https://github.com/sadeghi-sara/zipvan/blob/master/basic/train_logger.py"
click node_metrics "https://github.com/sadeghi-sara/zipvan/blob/master/basic/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_formatter toneBlue
class node_line_main,node_line_model,node_line_trainer,node_iam toneAmber
class node_paragraph_main,node_paragraph_model,node_paragraph_trainer toneMint
class node_dataset,node_transforms,node_training,node_base_models,node_presets,node_optimizer,node_scaling,node_logger,node_metrics toneRose
class node_user toneIndigo
```

## Components

### Data preparation

- [IAM formatter](https://github.com/sadeghi-sara/zipvan/blob/master/Datasets/format_datasets.py): `Datasets/format_datasets.py`

### Line recognition

- [Line run and evaluation](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/main_line_ctc.py): `OCR/line_OCR/ctc/main_line_ctc.py`
- [Line CTC models](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/models_line_ctc.py): `OCR/line_OCR/ctc/models_line_ctc.py`
- [Line CTC trainer](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/line_OCR/ctc/trainer_line_ctc.py): `OCR/line_OCR/ctc/trainer_line_ctc.py`

### Paragraph recognition

- [Paragraph run and evaluation](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/main_pg_va.py): `OCR/document_OCR/v_attention/main_pg_va.py`
- [Vertical attention model](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/models_pg_va.py): `OCR/document_OCR/v_attention/models_pg_va.py`
- [Paragraph trainer](https://github.com/sadeghi-sara/zipvan/blob/master/OCR/document_OCR/v_attention/trainer_pg_va.py): `OCR/document_OCR/v_attention/trainer_pg_va.py`

### Shared training core

- [Dataset manager](https://github.com/sadeghi-sara/zipvan/blob/master/basic/generic_dataset_manager.py): `basic/generic_dataset_manager.py`
- [Image transforms](https://github.com/sadeghi-sara/zipvan/blob/master/basic/transforms.py): `basic/transforms.py`
- [Training manager](https://github.com/sadeghi-sara/zipvan/blob/master/basic/generic_training_manager.py): `basic/generic_training_manager.py`
- [Encoder building blocks](https://github.com/sadeghi-sara/zipvan/blob/master/basic/models.py): `basic/models.py`
- [Training presets](https://github.com/sadeghi-sara/zipvan/blob/master/basic/presets.py): `basic/presets.py`
- [ScaledAdam and Eden](https://github.com/sadeghi-sara/zipvan/blob/master/basic/scaled_optimizer.py): `basic/scaled_optimizer.py`
- [Scaling layers](https://github.com/sadeghi-sara/zipvan/blob/master/basic/scaling.py): `basic/scaling.py`
- [Training logger](https://github.com/sadeghi-sara/zipvan/blob/master/basic/train_logger.py): `basic/train_logger.py`
- [OCR metrics](https://github.com/sadeghi-sara/zipvan/blob/master/basic/utils.py): `basic/utils.py`

### Other components

- **Researcher**
- **IAM dataset**

## Connections

- Researcher → IAM formatter: formats data (evidence: `README.md`)
- IAM dataset → IAM formatter: provides source (evidence: `README.md`)
- IAM formatter → Dataset manager: writes formatted data (evidence: `README.md`)
- Researcher → Line run and evaluation: starts line run (evidence: `README.md`)
- Line run and evaluation → Line CTC trainer: creates trainer (evidence: `OCR/line_OCR/ctc/main_line_ctc.py`)
- Line run and evaluation → Line CTC models: configures model (evidence: `OCR/line_OCR/ctc/main_line_ctc.py`)
- Line run and evaluation → Dataset manager: configures datasets (evidence: `OCR/line_OCR/ctc/main_line_ctc.py`)
- Line run and evaluation → Training presets: selects preset (evidence: `OCR/line_OCR/ctc/main_line_ctc.py`)
- Line CTC trainer → Training manager: inherits training (evidence: `OCR/line_OCR/ctc/trainer_line_ctc.py`)
- Line CTC trainer → Line CTC models: runs encoder and decoder (evidence: `OCR/line_OCR/ctc/trainer_line_ctc.py`)
- Line CTC trainer → OCR metrics: uses OCR metrics (evidence: `OCR/line_OCR/ctc/trainer_line_ctc.py`)
- Researcher → Paragraph run and evaluation: starts paragraph run (evidence: `README.md`)
- Paragraph run and evaluation → Paragraph trainer: creates trainer (evidence: `OCR/document_OCR/v_attention/main_pg_va.py`)
- Paragraph run and evaluation → Vertical attention model: configures model (evidence: `OCR/document_OCR/v_attention/main_pg_va.py`)
- Paragraph run and evaluation → Dataset manager: configures datasets (evidence: `OCR/document_OCR/v_attention/main_pg_va.py`)
- Paragraph run and evaluation → Training presets: selects preset (evidence: `OCR/document_OCR/v_attention/main_pg_va.py`)
- Paragraph run and evaluation → Line run and evaluation: loads line checkpoint (evidence: `README.md`)
- Paragraph trainer → Training manager: inherits training (evidence: `OCR/document_OCR/v_attention/trainer_pg_va.py`)
- Paragraph trainer → Vertical attention model: runs attention decoder (evidence: `OCR/document_OCR/v_attention/trainer_pg_va.py`)
- Dataset manager → Image transforms: uses transforms (evidence: `basic/generic_dataset_manager.py`)
- Training manager → Dataset manager: uses datasets (evidence: `basic/generic_training_manager.py`)
- Training manager → Training logger: logs training (evidence: `basic/generic_training_manager.py`)
- Training presets → ScaledAdam and Eden: configures optimizer (evidence: `basic/presets.py`)
- Encoder building blocks → Scaling layers: uses scaling (evidence: `basic/models.py`)