# mayocream/koharu architecture

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

- Interactive diagram: https://gitdiagram.com/mayocream/koharu
- Repository: https://github.com/mayocream/koharu

## Overview

##### Project Type and Purpose
- This is a full-stack, desktop-first application written in Rust + TypeScript (Next.js) that provides an ML-powered manga translation workflow.
- It combines a GUI (Tauri + React/Next.js) with a Rust backend that hosts multiple “sub-crates” for core utilities, ML inference, rendering, and runtime support.
- It can also run headless as a local HTTP server for non-GUI usage.

##### File Structure Analysis
Top-level crates and directories:
- koharu-core: common utilities (downloading, HTTP, progress tracking).
- koharu-ml: model loading & inference (comic-text detection, OCR, inpainting, LLM translation).
- koharu-runtime: dynamic library management (CUDA/Metal/zip/fonts).
- koharu: main application (Tauri backend, orchestrates all sub-crates, exposes RPC & CLI server).
- ui: Next.js/Tauri-driven GUI (React components, RPC client, canvas, panels).
- scripts: Python/TS scripts for model conversion, dataset prep, dev tasks.

##### README Insights
- Emphasizes local ML inference (no external servers), supports GPU acceleration via CUDA/Metal or CPU fallback.
- Uses Hugging Face “candle” for GGUF model loading, auto-downloads models from HF Hub.
- GUI layer built on Tauri for desktop, with headless HTTP-server fallback on a configurable port.

##### Main Components & Interactions
a. Components
1. GUI Layer
- Next.js frontend (ui/app)
- React components (canvas, panels, menus)
2. Tauri Backend / RPC Server
- koharu/src/server.rs and RPC abstraction (JSON-RPC over IPC or HTTP)
3. Core Utilities
- koharu-core: download manager, HTTP wrapper, progress indicator
4. ML Inference Engine
- koharu-ml:
- comic-text-detector
- font-detector
- manga-ocr
- inpainting (Lama via candle FFT backends)
- LLM translation (quantized models via candle)
5. Rendering Engine
6. Runtime Support
- koharu-runtime: dynamic library loader for CUDA/Metal, zip (.khr) file I/O, font management
7. Persistence / File I/O
- Reads/writes `.khr` archives, local caches for models, user settings
8. External Services
- Hugging Face Hub for model downloads
- Optional Discord support link (out-of-band)

b. Relationships & Data Flow
1. User interacts with GUI → triggers RPC calls to Tauri backend.
2. Tauri backend dispatches tasks to:
- Core utilities (download, progress)
- ML engine for detection, OCR, inpainting, translation
- Rendering engine for compositing translated text onto images
3. ML engine may download models via koharu-core’s HTTP client from HF Hub.
4. Runtime support loads GPU libraries (CUDA/Metal) before ML tasks.
5. Final images and `.khr` archives are saved via zip layer in runtime.
6. In headless mode, Tauri backend also hosts an HTTP server on the specified port.

c. Architectural Patterns & Principles
- Modular “crate” separation by concern (core, ML, rendering, runtime).
- Clear boundary between UI (Next.js) and backend logic (Rust/Tauri RPC).
- Plugin-style ML modules (each model category in its own Rust module).
- CI/CD and workspace management via Cargo workspace with uniform versioning.

d. Key Technologies & Frameworks
- Rust ecosystem: Cargo workspaces, Tauri, candle (Hugging Face inference), safetensors.
- Frontend: Next.js (app router), React, TypeScript, Tailwind CSS (via postcss).
- GPU acceleration: CUDA (NVIDIA), Metal (Apple Silicon), CPU fallback.
- Model resources: Hugging Face Hub, local cache via HTTP.

- Clear labels for all 7 major components/layers.
- Annotations for key tech (Tauri, Next.js, candle, CUDA/Metal).
- A note on headless mode’s HTTP server and port configuration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        UI_App["Next.js Frontend"]:::ui
        UI_Comp["React Components"]:::ui
        UI_Lib["RPC Client & Helpers"]:::ui
    end

    %% IPC/API Layer
    subgraph "IPC/API Layer"
        RPC["Tauri IPC/HTTP Server"]:::backend
    end

    %% Core Services Layer
    subgraph "Core Services Layer"
        Core["Core Utilities"]:::backend
    end

    %% Runtime Support Layer
    subgraph "Runtime Support Layer"
        Runtime["Runtime Support"]:::runtime
    end

    %% ML Inference Layer
    subgraph "ML Inference Layer"
        ML["ML Inference Engine"]:::ml
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        Renderer["Rendering Engine"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        Pers["Persistence (.khr & Cache)"]:::persistence
    end

    %% Headless Scripts
    subgraph "Headless Mode"
        Scripts["Headless Mode Scripts"]:::backend
    end

    %% External Services
    subgraph "External Services"
        External["Hugging Face Hub"]:::external
    end

    %% Connections
    User(("User")):::external -->|"Interacts With"| UI_App
    UI_App -->|"Uses Components"| UI_Comp
    UI_App -->|"Calls RPC"| RPC
    UI_Lib -->|"RPC Client"| RPC

    RPC -->|"Orchestrates"| Orchestrator["Main App Orchestrator"]:::backend
    Orchestrator -->|"Uses Core"| Core
    Orchestrator -->|"Loads GPU Libraries"| Runtime
    Orchestrator -->|"Runs ML Tasks"| ML
    Orchestrator -->|"Runs Rendering"| Renderer
    Orchestrator -->|"Reads/Writes"| Pers

    ML -->|"Downloads Models"| Core
    ML -->|"Fetch From"| External
    Runtime -->|"Provides GPU Support"| ML

    Scripts -->|"Starts Headless Server"| Orchestrator

    %% Click Events
    click UI_App "https://github.com/mayocream/koharu/tree/main/ui/app"
    click UI_Comp "https://github.com/mayocream/koharu/tree/main/ui/components"
    click UI_Lib "https://github.com/mayocream/koharu/tree/main/ui/lib"
    click RPC "https://github.com/mayocream/koharu/blob/main/koharu/src/server.rs"
    click Core "https://github.com/mayocream/koharu/blob/main/koharu-core/src/lib.rs"
    click Core "https://github.com/mayocream/koharu/blob/main/koharu-core/src/download.rs"
    click Core "https://github.com/mayocream/koharu/blob/main/koharu-core/src/http.rs"
    click Core "https://github.com/mayocream/koharu/blob/main/koharu-core/src/hf_hub.rs"
    click Core "https://github.com/mayocream/koharu/blob/main/koharu-core/src/progress.rs"
    click Runtime "https://github.com/mayocream/koharu/blob/main/koharu-runtime/src/lib.rs"
    click Runtime "https://github.com/mayocream/koharu/blob/main/koharu-runtime/src/dylib.rs"
    click Runtime "https://github.com/mayocream/koharu/blob/main/koharu-runtime/src/fonts.rs"
    click Runtime "https://github.com/mayocream/koharu/blob/main/koharu-runtime/src/zip.rs"
    click ML "https://github.com/mayocream/koharu/blob/main/koharu-ml/src/lib.rs"
    click Renderer "https://github.com/mayocream/koharu/blob/main/koharu-renderer/src/lib.rs"
    click Pers "https://github.com/mayocream/koharu/blob/main/koharu/src/khr.rs"
    click Pers "https://github.com/mayocream/koharu/blob/main/koharu-runtime/src/zip.rs"
    click Orchestrator "https://github.com/mayocream/koharu/blob/main/koharu/src/main.rs"
    click Scripts "https://github.com/mayocream/koharu/blob/main/scripts/start_headless.sh"
    click Scripts "https://github.com/mayocream/koharu/blob/main/scripts/start_headless.bat"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef ml fill:#fff3cd,stroke:#856404,color:#856404
    classDef runtime fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef persistence fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef external fill:#f0f0f0,stroke:#999999,color:#333333
```
