# sbrunner/deskew architecture

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

- Interactive diagram: https://gitdiagram.com/sbrunner/deskew
- Repository: https://github.com/sbrunner/deskew

## Overview

##### Project Type and Purpose
- Type: A small, single-module Python library + CLI tool for skew detection and correction in text-containing images.
- Purpose: Provide both a programmatic API (`determine_skew`) and a command-line utility (`deskew`) to compute and apply deskew rotations, with optional debug-image generation.

##### File Structure
- Top-level package: `deskew/`
- `__init__.py`: exposes `determine_skew` (core algorithm) and debug variants
- `cli.py`: command-line entry point
- Supporting files:
- `pyproject.toml`, `README.md`, `LICENSE` (packaging, docs)
- `tests/`: automated tests for core functionality
- `doc/`: sample input/output images
- `.github/`, `ci/`: CI pipelines & automation
- No external microservices—pure local execution.

##### README for Additional Insights
- Two main usage modes:
a) CLI (“deskew input.png”), optional `--output`
b) Library (import, call `determine_skew`, pass result to a rotate function from skimage/OpenCV)
- Optional debug-image generation when installed with extras.
- Underlying dependencies: NumPy, scikit-image or OpenCV.

##### Main Components & Interactions
a. Components:
1. User Interface
– CLI (`deskew` command)
– Library API (`determine_skew`, `determine_skew_debug_images`)
2. Core Algorithm
– Skew detection logic (Hough transform, peak detection)
– Parameterization (`num_peaks`, `min_angle`, etc.)
3. Image I/O & Processing
– Read image (via scikit-image or OpenCV)
– Convert to grayscale
– Compute skew angle
– Rotate image (using transform/warp functions)
– Write output image
4. Packaging & Distribution
– `pyproject.toml`, PyPI pipeline
5. Testing & CI
– Unit tests (`tests/test_deskew.py`)
– GitHub Actions workflows (`.github/workflows`)
– Pre-commit hooks (`.pre-commit-config.yaml`)
b. Relationships/Flow:
– User invokes CLI → CLI parses args → calls library core → library loads image → detection pipeline → returns angle → rotation pipeline → writes output → CLI returns exit code.
– Library API clients follow same core pipeline sans CLI parsing.
– Tests exercise core logic and CLI wrapper.
– CI pipelines build, test, lint, and publish package.
c. Architectural Patterns & Principles
– Single Responsibility: CLI logic separated from core algorithm
– Modular layering:
Layer-1: Interface (CLI / API)
Layer-2: Core algorithm (detection + debug)
Layer-3: I/O & image manipulation
– Dependency Injection: algorithm parameters pluggable via function arguments
d. Key Technologies & Libraries
– Python 3.x, NumPy
– scikit-image (default) or OpenCV (alternative)
– Click or argparse (CLI parsing)
– pytest (testing)
– GitHub Actions (CI/CD)

##### Elements
- “CLI Entry Point”
- “Library API”
- “Skew Detection Engine”
- “Image I/O & Rotation Module”
- “Debug-Image Generator”
- “Third-Party Libraries”
- “Unit Tests”
- “CI/CD Pipelines”
- From User → CLI/API → Skew Engine → Rotation → Filesystem
- Tests → Core & CLI
- CI → Code Repository → PyPI
- API/CLI = blue rectangles
- Core algorithm = green octagon
- Tests/CI = yellow parallelograms

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        CLI["CLI Entry Point"]:::api
        API["Library API"]:::api
    end

    %% Core Layer
    subgraph "Core Layer"
        Engine["Skew Detection Engine"]:::core
        IO["Image I/O & Rotation Module"]:::core
        Debug["Debug-Image Generator"]:::core
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        NP["NumPy"]:::ext
        SKI["scikit-image/OpenCV"]:::ext
        PyPI["PyPI"]:::ext
    end

    %% Testing & CI
    subgraph "Testing & CI"
        Tests["Unit Tests"]:::ci
        CI1["CI Workflow: main"]:::ci
        CI2["CI Workflow: pull-request"]:::ci
        CIReq["CI Requirements"]:::ci
        PreCommit["Pre-commit Hooks"]:::ci
        Prospector["Code Quality Config"]:::ci
    end

    %% Packaging & Docs
    subgraph "Packaging & Docs"
        PyProj["pyproject.toml"]:::pack
        README["README.md"]:::pack
        Doc["doc/ (sample images)"]:::pack
        Type["Type Hinting Marker"]:::pack
    end

    %% Data Flows
    User["User"]:::external -->|"invokes"| CLI
    User -->|"imports & calls"| API
    CLI -->|"calls"| Engine
    API -->|"calls"| Engine
    Engine -->|"processes image"| IO
    Engine -->|"generates debug data"| Debug
    IO -->|"writes output image"| FileSystem["Filesystem"]:::ext
    Engine -.-> NP
    Engine -.-> SKI
    IO -.-> SKI

    Tests -->|"tests CLI & Core"| CLI
    Tests -->|"tests API & Core"| API

    CI1 -->|"runs tests, lint, publish"| Tests
    CI1 -->|"uses"| CIReq
    CI1 -->|"uses"| PreCommit
    CI1 -->|"uses"| Prospector
    CI1 -->|"publishes to"| PyPI

    CI2 -->|"PR checks"| Tests
    CI2 -->|"uses"| CIReq
    CI2 -->|"uses"| PreCommit
    CI2 -->|"uses"| Prospector

    PyProj -->|"packaging config"| PyPI
    README -->|"documentation"| User
    Doc -->|"sample I/O"| User
    Type -.-> API

    %% Click Events
    click CLI "https://github.com/sbrunner/deskew/blob/master/deskew/cli.py"
    click API "https://github.com/sbrunner/deskew/blob/master/deskew/__init__.py"
    click Engine "https://github.com/sbrunner/deskew/blob/master/deskew/__init__.py"
    click Debug "https://github.com/sbrunner/deskew/blob/master/deskew/__init__.py"
    click PyProj "https://github.com/sbrunner/deskew/blob/master/pyproject.toml"
    click README "https://github.com/sbrunner/deskew/blob/master/README.md"
    click Doc "https://github.com/sbrunner/deskew/tree/master/doc/"
    click Tests "https://github.com/sbrunner/deskew/blob/master/tests/test_deskew.py"
    click CI1 "https://github.com/sbrunner/deskew/blob/master/.github/workflows/main.yaml"
    click CI2 "https://github.com/sbrunner/deskew/blob/master/.github/workflows/pull-request-automation.yaml"
    click CIReq "https://github.com/sbrunner/deskew/blob/master/ci/requirements.txt"
    click PreCommit "https://github.com/sbrunner/deskew/blob/master/.pre-commit-config.yaml"
    click Prospector "https://github.com/sbrunner/deskew/blob/master/.prospector.yaml"
    click Type "https://github.com/sbrunner/deskew/blob/master/deskew/py.typed"

    %% Styles
    classDef api fill:#E0F7FA,stroke:#006064,stroke-width:2px
    classDef core fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px
    classDef ext fill:#ECEFF1,stroke:#455A64,stroke-width:2px
    classDef ci fill:#FFF3E0,stroke:#E65100,stroke-width:2px
    classDef pack fill:#F3E5F5,stroke:#4A148C,stroke-width:2px
    classDef external fill:#FFFFFF,stroke:#000000,stroke-width:1px,stroke-dasharray: 2 2
```
