# mittagessen/kraken architecture

> Architecture diagram of the GitHub repository mittagessen/kraken, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mittagessen/kraken
- Repository: https://github.com/mittagessen/kraken

## Overview

##### Project Type and Purpose
- Kraken is a domain-specific, full-stack OCR system optimized for historical and non-Latin scripts.
- It provides both a CLI interface for local inference/training (kraken command) and a Python library (`kraken.lib`), plus an optional HTTP service layer (`kraken.ketos`) with static web assets for integration.

##### High-Level Architecture
A. CLI Application Layer
B. Core Processing Library
C. Optional HTTP/REST Service Layer (Ketos)
D. External & Deployment Components

##### Main Components & Relationships
A. CLI Application Layer
- Entry point: `kraken/kraken.py` invokes subcommands: binarize, segment, ocr, train, get, list, etc.
- Orchestrates pipelines by calling into Core Processing Library.
- Reads user inputs (image files, options), writes outputs (text, JSON, XML).
B. Core Processing Library (`kraken.lib` + `kraken` modules)
- Binarization: `kraken.binarization`, `kraken.lib.functional_im_transforms`
- Segmentation: `kraken.pageseg`, `kraken.lib.segmentation`, `kraken.lib/dataset/segmentation.py`
- Line & layout analysis: `kraken.align`, `kraken.blla`
- Recognition: model architectures in `kraken.lib.models`, `kraken.lib.pretrain`, `kraken.lib.ro`
- Inference & decoding: `kraken.lib.ctc_decoder`, `kraken.lib.xml`, `kraken.rpred`, `kraken/transcribe.py`
- Data handling: `kraken.lib.dataset`, `kraken.lib.util`, `kraken.containers`
- Contrib scripts for extended functionality: `kraken/contrib/*.py`
C. Optional HTTP/REST Service Layer (Ketos)
- Package: `kraken.ketos`
- Exposes endpoints for training, dataset management, segmentation, recognition, transcription.
- Serves static assets (HTML, CSS, JS) from `kraken/templates` for a minimal front-end.
- Interacts with the same core modules to perform tasks on server side.
D. External & Deployment Components
- Model repository: downloads from Zenodo (via CLI `kraken get`)
- Output formats: ALTO, PageXML, ABBYYXML, hOCR via template system (`kraken/templates/*`)
- Packaging: `setup.py`, `pyproject.toml`, `environment.yml` (CPU/GPU), `singularity/kraken.def`
- CI: `.github/workflows/test.yml`, `pytest.ini`, `tests/`

##### Data Flow & Interactions
- User invokes the CLI or sends HTTP request → CLI/Ketos layer
- CLI/Ketos calls Core Library functions in order:
1. Load image(s) → Binarization → Segmentation → Line estimation → Recognition
3. Serialize results in user-specified format (text, JSON, XML)
- Contrib scripts can be plugged in to augment overlays, heatmaps, forced alignment, etc.

##### Architectural Patterns & Design Principles
- Modular pipeline design: each OCR stage is a separate module, callable independently.
- Plugin-style I/O: format templates exist under `kraken/templates`; formatters are interchangeable.
- Layered separation:
- Presentation (CLI + Ketos web assets)
- Orchestration (kraken/kraken.py + ketos router)
- Processing core (kraken.lib + algorithm modules)
- Data storage (models, datasets, cache)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layers
    CLI["CLI Application"]:::presentation
    click CLI "https://github.com/mittagessen/kraken/blob/main/kraken/kraken.py"
    Ketos["HTTP REST Service (Ketos)"]:::presentation
    click Ketos "https://github.com/mittagessen/kraken/tree/main/kraken/ketos/"

    %% Core Processing Library
    subgraph "Core Processing Library" 
        direction TB
        Bin["Binarization"]:::core
        click Bin "https://github.com/mittagessen/kraken/blob/main/kraken/binarization.py"
        click Bin "https://github.com/mittagessen/kraken/blob/main/kraken/lib/functional_im_transforms.py"

        Seg["Segmentation"]:::core
        click Seg "https://github.com/mittagessen/kraken/blob/main/kraken/pageseg.py"
        click Seg "https://github.com/mittagessen/kraken/blob/main/kraken/lib/segmentation.py"
        click Seg "https://github.com/mittagessen/kraken/blob/main/kraken/lib/dataset/segmentation.py"

        Line["Line & Layout Analysis"]:::core
        click Line "https://github.com/mittagessen/kraken/blob/main/kraken/align.py"
        click Line "https://github.com/mittagessen/kraken/blob/main/kraken/blla.py"

        Recog["Recognition & Models"]:::core
        click Recog "https://github.com/mittagessen/kraken/blob/main/kraken/lib/models.py"
        click Recog "https://github.com/mittagessen/kraken/blob/main/kraken/lib/pretrain/model.py"
        click Recog "https://github.com/mittagessen/kraken/blob/main/kraken/lib/pretrain/layers.py"
        click Recog "https://github.com/mittagessen/kraken/blob/main/kraken/lib/ro/model.py"
        click Recog "https://github.com/mittagessen/kraken/blob/main/kraken/lib/ro/layers.py"

        Decode["Inference & Decoding"]:::core
        click Decode "https://github.com/mittagessen/kraken/blob/main/kraken/lib/ctc_decoder.py"
        click Decode "https://github.com/mittagessen/kraken/blob/main/kraken/rpred.py"
        click Decode "https://github.com/mittagessen/kraken/blob/main/kraken/transcribe.py"
        click Decode "https://github.com/mittagessen/kraken/blob/main/kraken/lib/xml.py"

        Data["Data Handling & Utilities"]:::core
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/lib/dataset/recognition.py"
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/lib/dataset/ro.py"
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/lib/dataset/segmentation.py"
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/lib/dataset/utils.py"
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/lib/util.py"
        click Data "https://github.com/mittagessen/kraken/blob/main/kraken/containers.py"

        Contrib["Contrib Scripts"]:::core
        click Contrib "https://github.com/mittagessen/kraken/tree/main/kraken/contrib/"
    end

    %% Output Formatters & Templates
    subgraph "Output Formatters & Templates" 
        Templates["Format Templates (ALTO/ABBYXML/hOCR/PageXML)"]:::io
        click Templates "https://github.com/mittagessen/kraken/tree/main/kraken/templates/"
    end

    ModelStore["Local Model Store"]:::io
    ExternalRepo["External Model Repo (Zenodo)"]:::external
    Deployment["Packaging & CI & Tests"]:::external

    %% Data Flow
    CLI -->|"image (.tif)"| Bin
    Ketos -->|"image (.tif)"| Bin
    Bin -->|"binary image"| Seg
    Seg -->|"segments"| Line
    Line -->|"lines"| Recog
    Recog -->|"activations"| Decode
    Decode -->|"texts & probabilities"| Templates
    Templates -->|"formatted output (XML/JSON)"| CLI
    Templates -->|"formatted output (XML/JSON)"| Ketos
    Decode -->|"model (.mlmodel)"| ModelStore
    CLI -->|"get model"| ExternalRepo

    %% Connections to Core Data
    Contrib -.-> Data
    Data -.-> Recog

    %% Deployment connections
    CLI --> Deployment
    Ketos --> Deployment

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef core fill:#E2F7E1,stroke:#2E7D32,color:#2E7D32,stroke-width:1px;
    classDef io fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D,stroke-width:1px;
```
