# t0mer/ocr-docker architecture

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

- Interactive diagram: https://gitdiagram.com/t0mer/ocr-docker
- Repository: https://github.com/t0mer/ocr-docker

## Overview

##### Main Components
- **User / Browser**
The user interacts via a web browser, uploads images/PDFs, and views extracted text.
- **Frontend (Flask-served Static UI)**
ocr/templates/index.html + ocr/css/*.css + ocr/js/*.js + ocr/fonts/*
– Delivers the upload form and displays results.
- **Backend (Flask Application)**
ocr/ocr.py
– Defines routes (e.g. POST /upload), orchestrates preprocessing, calls OCR, returns JSON or renders HTML.
– Uses Python libraries: Flask, Loguru (logging), PyYAML (config), Pillow & image (image I/O), pytesseract (binding).
- **Image / PDF Preprocessing**
– **Ghostscript** for PDF→image conversion.
– **ImageMagick** for image cleanup, format conversion, resizing.
- **OCR Engine**
– **Tesseract-OCR** binary, invoked via pytesseract or subprocess.
– **Tessdata language models** (traineddata/*).
- **Containerization & Deployment**
– **Dockerfile** builds image with all dependencies.
– **docker-compose.yaml** defines service, port mapping (8080).
- **CI / QA**
– .github/workflows/docker-image.yml (build & push)
– .github/workflows/sonarcloud.yml (static analysis)

##### Relationships & Data Flow
User → HTTP Request → Flask App →
- If PDF: Ghostscript → images → ImageMagick → cleaned images →
- If image: optional ImageMagick →
→ Tesseract (with selected traineddata) → extracted text → Flask App → HTTP Response → User.

##### Architectural Patterns & Principles
- **Separation of Concerns**:
- Static UI assets served separately from core logic in ocr.py.
- Preprocessing, OCR, and I/O each encapsulated in distinct modules or subprocess calls.
- **12-Factor / Twelve-Factor-App** (in container):
- Config via environment variables (in Docker).
- Dependencies declared in requirements, image deterministic.
- **Stateless Processing**:
- No persistent DB; ephemeral files only.
- Logs via Loguru.

##### Technologies & Frameworks
- Flask (web server / routing)
- Python libs: Pillow, pytesseract, Loguru, PyYAML
- CLI tools: Tesseract-OCR, Ghostscript, ImageMagick
- Container: Docker, Docker-Compose
- CI: GitHub Actions, SonarCloud

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        User["User Browser"]:::external
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Flask["Flask App"]:::backend
        Template["Template: index.html"]:::frontend
        CSSDir["Static CSS: ocr/css/"]:::frontend
        JS["JavaScript: form-scripts.js"]:::frontend
        Fonts["Fonts: ocr/fonts/"]:::frontend
    end

    %% Processing Layer
    subgraph "Processing Layer"
        GS["Ghostscript"]:::processing
        IM["ImageMagick"]:::processing
        TESS["Tesseract-OCR + traineddata"]:::processing
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yaml"]:::infra
        CI1["GitHub Actions:\docker-image.yml"]:::ci
        CI2["GitHub Actions:\sonarcloud.yml"]:::ci
    end

    %% Data Flow
    User -->|"HTTP POST /upload"| Flask
    Flask -->|"subprocess: ghostscript"| GS
    GS -->|"PDF→images"| IM
    Flask -->|"optional subprocess: convert"| IM
    IM -->|"cleaned images"| TESS
    Flask -->|"pytesseract/subprocess: tesseract"| TESS
    TESS -->|"extracted text"| Flask
    Flask -->|"HTTP Response (text)"| User

    %% Click Events
    click Template "https://github.com/t0mer/ocr-docker/blob/main/ocr/templates/index.html"
    click CSSDir "https://github.com/t0mer/ocr-docker/tree/main/ocr/css/"
    click JS "https://github.com/t0mer/ocr-docker/blob/main/ocr/js/form-scripts.js"
    click Fonts "https://github.com/t0mer/ocr-docker/tree/main/ocr/fonts/"
    click Flask "https://github.com/t0mer/ocr-docker/blob/main/ocr/ocr.py"
    click TESS "https://github.com/t0mer/ocr-docker/tree/main/traineddata/"
    click DockerfileNode "https://github.com/t0mer/ocr-docker/tree/main/Dockerfile"
    click Compose "https://github.com/t0mer/ocr-docker/blob/main/docker-compose.yaml"
    click CI1 "https://github.com/t0mer/ocr-docker/blob/main/.github/workflows/docker-image.yml"
    click CI2 "https://github.com/t0mer/ocr-docker/blob/main/.github/workflows/sonarcloud.yml"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef backend fill:#90caf9,stroke:#1565c0,stroke-width:1px
    classDef processing fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef ci fill:#fff9c4,stroke:#f9a825,stroke-width:1px
```
