# text2knowledge/doctr-labeler architecture

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

- Interactive diagram: https://gitdiagram.com/text2knowledge/doctr-labeler
- Repository: https://github.com/text2knowledge/doctr-labeler

## Overview

##### Project type and purpose
- This is an open-source, Python-based desktop annotation tool (“docTR Labeler”) for OCR data.

##### Main components and directories
- CLI launcher (labeler/cli/main.py)
- GUI layer (labeler/views/gui.py)
- Canvas view (labeler/views/canvas.py)
- Drawing primitives & domain model (labeler/components/*.py: polygon, draw_poly)
- Automation & auto-annotation (labeler/automation/auto_labeler.py, tight_box.py)
- Utilities (labeler/utils/data_utils.py for preparing folders, hub_factory.py for HF uploads)
- Logger (labeler/logger.py)
- Data store (on-disk image folder + labels.json)
- External services:
- OnnxTR/DocTR inference (via automation modules)
- Hugging Face dataset hub (via hub_factory)

##### Relationships and data flows
- User invokes either
- CLI → labeler.cli.main → GUI or
- Programmatic API → GUI
- GUI instantiates Canvas, loads images from the data folder
- Auto-annotation: user triggers “auto adjust” → automation.auto_labeler calls OnnxTR detector & recognizer → returns polygons → Canvas updates view/model
- Save: GUI/Canvas serializes annotations to labels.json on disk
- (Optional) HF upload: utils.hf_upload_dataset reads images+labels.json → hub_factory pushes to remote

##### Architectural patterns and design principles
- MVC-ish separation:
- Views: GUI + Canvas
- Model: Polygon objects, internal state
- Controller: CLI entrypoint & automation logic
- Factory pattern: hub_factory creates HF dataset clients
- Plugin-style extensibility: detection/recognition architectures picked via environment variables

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Launcher"]:::frontend
        API["Programmatic API"]:::frontend
        GUI["GUI Layer"]:::frontend
        Canvas["Canvas View"]:::frontend
    end

    %% Business Logic
    subgraph "Business Logic"
        subgraph "Drawing Components"
            Polygon["Polygon Model"]:::logic
            DrawPoly["Draw Primitives"]:::logic
        end
        subgraph "Automation"
            AutoLabeler["Auto-Labeler Controller"]:::logic
            TightBox["Tight Box Helper"]:::logic
        end
        Logger["Logger"]:::logic
        subgraph "Utilities"
            DataUtils["Data Preparation Utils"]:::logic
            HubFactory["HF Hub Factory"]:::logic
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        Images["Images Folder"]:::data
        Labels["labels.json"]:::data
    end

    %% External Services
    subgraph "External Services"
        OnnxTR["OnnxTR/DocTR Service"]:::external
        HFHub["Hugging Face Hub"]:::external
    end

    %% Data Flows
    User["User"]:::external
    User --> CLI
    User --> API

    CLI -->|"launch GUI"| GUI
    API -->|"invoke GUI"| GUI

    GUI -->|"instantiate"| Canvas
    Canvas -->|"load images"| Images
    Canvas -->|"draw/update"| Polygon
    Canvas -->|"draw/update"| DrawPoly

    Canvas -->|"trigger auto adjust"| AutoLabeler
    AutoLabeler -->|"use helper"| TightBox
    AutoLabeler -->|"inference request"| OnnxTR
    OnnxTR -->|"inference response"| AutoLabeler
    AutoLabeler -->|"return polygons"| Canvas

    Canvas -->|"save annotations"| Labels

    DataUtils -->|"read images+labels"| Images
    DataUtils -->|"read images+labels"| Labels
    HubFactory -->|"push dataset"| HFHub

    %% Click Events
    click CLI "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/cli/main.py"
    click GUI "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/views/gui.py"
    click Canvas "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/views/canvas.py"
    click Polygon "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/components/polygon.py"
    click DrawPoly "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/components/draw_poly.py"
    click AutoLabeler "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/automation/auto_labeler.py"
    click TightBox "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/automation/tight_box.py"
    click DataUtils "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/utils/data_utils.py"
    click HubFactory "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/utils/hub_factory.py"
    click Logger "https://github.com/text2knowledge/doctr-labeler/blob/main/labeler/logger.py"

    %% Styles
    classDef frontend fill:#f2f2ff,stroke:#333,stroke-width:1px
    classDef logic fill:#e6f7ff,stroke:#333,stroke-width:1px
    classDef data fill:#e6ffe6,stroke:#333,stroke-width:1px
    classDef external fill:#fff5e6,stroke:#333,stroke-width:1px
```
