# kha-white/mokuro architecture

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

- Interactive diagram: https://gitdiagram.com/kha-white/mokuro
- Repository: https://github.com/kha-white/mokuro

## Overview

Based on our analysis of the file tree and README, mokuro is a Python-based command-line tool designed to perform offline OCR processing on Japanese manga volumes. Its goal is to extract selectable text from manga pages, generating either a legacy HTML file or a new .mokuro file (which is meant to be used with a separate web reader). The tool integrates external libraries (such as comic‐text‐detector for text detection and manga‐ocr for OCR) to process manga images into an output that can be read interactively in a browser.

##### Main Components
- CLI / Entry Point: The tool is executed from the command line. Look at files like mokuro/__main__.py and mokuro/run.py which serve as entry points.
- Core Processing Modules: This includes modules for OCR processing and file generation:
- mokuro/manga_page_ocr.py: Handles OCR processing for each page.
- mokuro/mokuro_generator.py: Responsible for generating the .mokuro file format.
- mokuro/volume.py: Likely used for representing and processing individual manga volumes.
- mokuro/cache.py: Implements caching logic for previously processed OCR results.
- mokuro/env.py: Manages environment config and settings.
- Legacy Support: The legacy directory (mokuro/legacy) contains modules (e.g., overlay_generator.py, script.js, styles.css) which support the old HTML output method.
- Dependencies/Integration: External tools/libraries are integrated:
- comic-text-detector: For detecting text in manga images.
- manga-ocr: For performing OCR on the detected regions.
- Testing & Automation: The tests directory ensures functionality is maintained with different input scenarios (including various formats and expected outputs).

##### Relationships and Data Flow
- Input:
- The user runs mokuro via the CLI and provides paths to manga volumes (either one, multiple, or a parent directory).
- Processing Pipeline:
- CLI calls the entry point (run.py/__main__.py).
- The application loads the manga pages and triggers text detection (via comic-text-detector) and then OCR (via manga-ocr).
- Processing modules like manga_page_ocr.py and volume.py handle the per-page and per-volume operations.
- Processing results may be cached in a dedicated _ocr directory (handled by cache.py).
- Output Generation:
- The mokuro_generator.py module takes the OCR output and converts it into a .mokuro file (with metadata and OCR results) for use with the separate web reader.
- In legacy mode, the legacy modules generate an HTML file that embeds the OCR results along with the web reader GUI.
- External Components:
- Optionally, include integration with external tools like Mokuro2Pdf or guides available in the ecosystem.

##### Architectural Patterns and Design Choices
- Dependency integration: Emphasize the interaction between mokuro and its OCR/text detection libraries. These components are invoked as external services or modules.
- Offline Processing: All file operations and OCR processing are done offline prior to reading, which is an important characteristic.
- Extensibility Points: The legacy support and configuration via command-line options show that the tool is designed to handle multiple processing workflows and to be integrated into a broader ecosystem of manga reading tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    userCLI["User CLI"]:::cli
    CLIEntry["CLI/Entry Point"]:::cli
    EnvConfig["Environment Config"]:::core
    VolumeProc["Volume Processing"]:::core
    OCRProc["OCR Processing"]:::core
    Cache["Caching Logic"]:::core
    ComicTextDetector["External: comic-text-detector"]:::external
    MangaOCR["External: manga-ocr"]:::external
    OutputGen["Output Generator (.mokuro File)"]:::core
    LegacyHTML["Legacy HTML Generator"]:::legacy
    LegacyAssets["Legacy Assets"]:::legacy
    WebReader["External: Web Reader"]:::external
    Tests["Tests"]:::test

    userCLI -->|"runs"| CLIEntry
    CLIEntry -->|"loads_config"| EnvConfig
    CLIEntry -->|"process_volume"| VolumeProc
    CLIEntry -->|"initiates_OCR"| OCRProc
    OCRProc -->|"cache_update"| Cache
    Cache -->|"returns_cached"| OCRProc
    OCRProc -->|"detects_text"| ComicTextDetector
    OCRProc -->|"performs_OCR"| MangaOCR
    VolumeProc -->|"sends_data"| OutputGen
    OCRProc -->|"sends_OCR_data"| OutputGen
    VolumeProc -->|"legacy_mode"| LegacyHTML
    OCRProc -->|"legacy_output"| LegacyHTML
    LegacyHTML -->|"includes_assets"| LegacyAssets
    OutputGen -->|"consumed_by"| WebReader
    CLIEntry -->|"triggers_tests"| Tests

    click CLIEntry "https://github.com/kha-white/mokuro/blob/master/mokuro/__main__.py"
    click CLIEntry "https://github.com/kha-white/mokuro/blob/master/mokuro/run.py"
    click OCRProc "https://github.com/kha-white/mokuro/blob/master/mokuro/manga_page_ocr.py"
    click OutputGen "https://github.com/kha-white/mokuro/blob/master/mokuro/mokuro_generator.py"
    click VolumeProc "https://github.com/kha-white/mokuro/blob/master/mokuro/volume.py"
    click Cache "https://github.com/kha-white/mokuro/blob/master/mokuro/cache.py"
    click EnvConfig "https://github.com/kha-white/mokuro/blob/master/mokuro/env.py"
    click LegacyHTML "https://github.com/kha-white/mokuro/tree/master/mokuro/legacy"
    click LegacyAssets "https://github.com/kha-white/mokuro/tree/master/mokuro/assets"
    click Tests "https://github.com/kha-white/mokuro/tree/master/tests"

    classDef cli fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef legacy fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef test fill:#ffebcc,stroke:#333,stroke-width:2px;
```
