# harish2704/pottan-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/harish2704/pottan-ocr
- Repository: https://github.com/harish2704/pottan-ocr

## Overview

##### Project type and purpose
- This is a specialized OCR engine for complex scripts (Malayalam) that provides:
- A core Python library (`pottan_ocr/…`) for data generation, model definition, training and inference
- A CLI wrapper (`bin/pottan`) exposing subcommands (extractWikiDump, datagen, train, ocr)
- An HTTP‐based OCR server (`pottan_ocr/ocr_server.py`) with a small static GUI (`gui/web`)
- A standalone browser demo (`web-demo/…`) that runs inference client-side via KerasJS/TF-JS
- Tooling scripts (`tools/…`) for data collection, glyph list generation and dependency installation

##### File structure
- Top level: project metadata, license, README, sample config
- `pottan_ocr/`: core engine modules
- data pipelines (`dataset.py`, `data_gen.py`, `custom_dataset.py`)
- model definition (`model.py`)
- training orchestration (`train.py`, `custom_training.py`)
- inference server (`ocr_server.py`, `ocr_hocr.py`)
- string conversion and utilities
- `bin/pottan`: entrypoint dispatching to the above modules
- `gui/web`: minimal static frontend for the Python OCR server
- `web-demo`: full JS/HTML/CSS demo built with KerasJS (Webpack, package.json)
- `tools`: shell/JS scripts for data collection, glyph list generation, installer

##### README for additional insights
- Core engine replaces Tesseract in Ocropy for single‐line recognition
- Training uses synthetic data (on‐the‐fly or cached) with fonts from system
- Dependencies: PyTorch, Ocropy, KerasJS, WebGL2
- Two usage modes: CLI & server + small GUI, and pure client‐side demo

a. Main components
1. Data Pipeline
- Wikipedia dump extractor (tools/collect-wiki-data.js)
- Glyph list generator (tools/gen-glyph-list.js)
- Synthetic data generator (`data_gen.py`)
2. Training Pipeline
- `train.py` & `custom_training.py` (PyTorch CRNN model)
- Cache directory for generated images
3. Model Repository
- Pretrained models pulled from GitHub (`pottan-ocr-data`)
4. Core OCR Engine
- `model.py`, `ocr_hocr.py`, `string_converter.py`
- Replaces Tesseract in Ocropy for line‐level recognition
5. CLI Interface
- `bin/pottan` command dispatcher
6. OCR Server + Static GUI
- `ocr_server.py` exposes REST endpoints (POST image → OCR result)
- Serves `gui/web/index.html`, CSS, JS
7. Client-side Web Demo
- `web-demo` folder: Webpack bundle (`app.pottan-tfjs.js`) runs model in browser
8. External Services & Dependencies
- Ocropy (layout detection, line segmentation)
- PyTorch (training / engine)
- KerasJS & WebGL2 (browser inference)

b. Relationships & interactions
- Tools → generate text corpus & fonts → feed into Data Pipeline
- Data Pipeline → synthetic images → Training Pipeline
- Training Pipeline → trained CRNN model → Model Repository
- CLI & Server both load model from Model Repository → Core OCR Engine
- OCR Server ↔ Static GUI (browser requests via HTTP)
- Web Demo (hosted or static serve) loads model artifact → runs inference client-side
- Core OCR Engine calls out to Ocropy for segmentation under the hood

c. Architectural patterns & design principles
- Modular Python library with clear separation of data, model, training, inference
- Single‐command CLI dispatcher (Command pattern)
- Thin server layer (REST API) with static asset serving (MVC-lite)
- Dual‐mode inference: server-side vs. client-side (decoupled frontends)
- Synthetic data generation on the fly (Cache-aside pattern)

d. Technologies
- Python, PyTorch, Ocropy, h5 model files
- Shell & NodeJS tooling scripts
- Flask or similar lightweight server in `ocr_server.py`
- HTML/CSS/JS for `gui/web`
- Webpack, KerasJS/TF-JS, WebGL2 for `web-demo`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Offline pipelines
    subgraph "Offline Pipelines"
        direction TB
        subgraph "Tooling Scripts"
            direction TB
            T1["Wiki Dump Extractor"]:::offline
            T2["Glyph List Generator"]:::offline
            T3["Batch Data Generator"]:::offline
            T4["Dependency Installer"]:::offline
        end
        subgraph "Data Pipeline"
            direction TB
            DP1["Synthetic Data Generator"]:::offline
            DP2["Dataset Definitions"]:::offline
        end
        subgraph "Training Pipeline"
            direction TB
            TP1["CRNN Training"]:::offline
        end
    end

    %% Core engine and model repo
    subgraph "Core OCR Engine & Model Repo"
        direction TB
        CE1["Model Definition"]:::core
        CE2["HOCR Inference"]:::core
        CE3["String Conversion"]:::core
        MR["Model Repository"]:::core
    end

    %% Frontends
    subgraph "Frontends"
        direction TB
        CLI["CLI Interface"]:::frontend
        SVR["OCR Server (REST API)"]:::frontend
        GUI["Static GUI"]:::frontend
        DEMO["Web Demo (Client-side)"]:::demo
    end

    %% External dependencies
    subgraph "External Dependencies"
        direction TB
        OC["Ocropy"]:::external
        PT["PyTorch"]:::external
        KJ["KerasJS/WebGL2"]:::external
    end

    %% Data flow connections
    T1 -->|extract text| DP1
    T2 -->|generate glyphs| DP1
    T3 -->|generate batch data| DP1
    DP1 -->|produce images| DP2
    DP2 -->|feeds data| TP1
    TP1 -->|save model.h5| MR

    %% Inference flow
    CLI -->|load model| CE1
    SVR -->|load model| CE1
    CE1 -->|segment lines| OC
    CE2 -->|format HOCR| CE3
    CE3 -->|return text| CLI
    CE3 -->|return JSON| SVR

    SVR -->|serves| GUI
    DEMO -->|load model client-side| MR
    DEMO -->|inference via| KJ

    %% Click events
    click T1 "https://github.com/harish2704/pottan-ocr/blob/master/tools/collect-wiki-data.js"
    click T2 "https://github.com/harish2704/pottan-ocr/blob/master/tools/gen-glyph-list.js"
    click T3 "https://github.com/harish2704/pottan-ocr/blob/master/tools/gen_data.sh"
    click T4 "https://github.com/harish2704/pottan-ocr/blob/master/tools/install-dependencies.sh"
    click DP1 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/data_gen.py"
    click DP2 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/dataset.py"
    click DP2 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/custom_dataset.py"
    click TP1 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/train.py"
    click TP1 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/custom_training.py"
    click CE1 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/model.py"
    click CE2 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/ocr_hocr.py"
    click CE3 "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/string_converter.py"
    click SVR "https://github.com/harish2704/pottan-ocr/blob/master/pottan_ocr/ocr_server.py"
    click GUI "https://github.com/harish2704/pottan-ocr/blob/master/gui/web/index.html"
    click GUI "https://github.com/harish2704/pottan-ocr/blob/master/gui/web/app.js"
    click DEMO "https://github.com/harish2704/pottan-ocr/tree/master/web-demo/"
    click DEMO "https://github.com/harish2704/pottan-ocr/blob/master/web-demo/js/app.pottan-tfjs.js"
    click DEMO "https://github.com/harish2704/pottan-ocr/blob/master/web-demo/css/app.css"
    click DEMO "https://github.com/harish2704/pottan-ocr/blob/master/web-demo/index.html"
    click DEMO "https://github.com/harish2704/pottan-ocr/blob/master/web-demo/webpack.config.js"
    click DEMO "https://github.com/harish2704/pottan-ocr/blob/master/web-demo/package.json"
    click CLI "https://github.com/harish2704/pottan-ocr/tree/master/bin/pottan"

    %% Styling
    classDef offline fill:#cce5ff,stroke:#4da3ff,color:#000;
    classDef core fill:#d4edda,stroke:#28a745,color:#000;
    classDef frontend fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef demo fill:#e2d6f3,stroke:#8e44ad,color:#000;
    classDef external fill:#f0f0f0,stroke:#999,color:#000;
```
