# aklid01/manhua architecture

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

- Interactive diagram: https://gitdiagram.com/aklid01/manhua
- Repository: https://github.com/aklid01/manhua

## Overview

This is a local-first manhua-to-English translation application. Its main workflow imports chapter images, detects text regions, runs OCR, translates and optionally paraphrases dialogue, renders English onto cleaned pages, performs QA, and optionally packages the result. Chapter workspaces hold editable intermediate JSON and support reruns or resumption. The graph also shows backend choices, glossary and manual-review support, the guided GUI, and touch-up editor. Stage sequencing and optional capabilities are documented in the README; unsampled stage implementations are represented by their exact paths, with no additional internal call relationships inferred.

Main entry points: [`manhua_pipeline/stages/stage3_translation/engine.py`](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/engine.py) (Literal translation), [`manhua_pipeline/stages/stage3_translation/backends.py`](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/backends.py) (Translation backends), [`pipeline.py`](https://github.com/aklid01/manhua/blob/main/pipeline.py) (Pipeline CLI), [`manhua_pipeline/stages/stage4_paraphrase.py`](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage4_paraphrase.py) (Dialogue paraphrase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Chapter workflow"]
  node_import["Chapter import<br/>[stage0_import.py]"]
  node_detection["Region detection"]
  node_ocr["Text OCR<br/>[stage2_ocr.py]"]
end

subgraph group_language["Translation and review"]
  node_translation["Literal translation<br/>[engine.py]"]
  node_translation_backends["Translation backends<br/>[backends.py]"]
  node_openai["OpenAI-compatible client<br/>[_openai_compat.py]"]
  node_validation["Translation validation"]
  node_triage["Translation triage<br/>[triage.py]"]
  node_glossary[("Series glossary<br/>[glossary_series.py]")]
  node_overrides[("Manual overrides")]
  node_paraphrase["Dialogue paraphrase"]
  node_mcp["MCP interface<br/>[mcp_server.py]"]
end

subgraph group_rendering["Rendering and quality"]
  node_render["Page rendering<br/>[engine.py]"]
  node_geometry["Render geometry<br/>[geometry.py]"]
  node_qa["Quality assurance<br/>[stage6_qa.py]"]
  node_package["ZIP / CBZ packaging<br/>[stage7_package.py]"]
  node_touchup["Touch-up editor<br/>[app.py]"]
end

subgraph group_support["Workspace and interfaces"]
  node_cli["Pipeline CLI<br/>[pipeline.py]"]
  node_gui["Guided GUI<br/>[pipeline_gui.py]"]
  node_workspace[("Chapter workspace<br/>[workspace.py]")]
  node_events["Pipeline events<br/>[events.py]"]
  node_event_emitter["Event emitter<br/>[event_emitter.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_config["Pipeline configuration<br/>[config.py]"]
end

node_reader(("Reader / translator"))

node_reader -->|"runs commands"| node_cli
node_reader -->|"uses guided flow"| node_gui
node_cli -->|"runs stages"| node_import
node_gui -->|"opens editor"| node_touchup
node_import -->|"next stage"| node_detection
node_detection -->|"next stage"| node_ocr
node_ocr -->|"next stage"| node_translation
node_translation -->|"next stage"| node_paraphrase
node_paraphrase -->|"next stage"| node_render
node_render -->|"next stage"| node_qa
node_qa -.->|"optional packaging"| node_package
node_translation -->|"uses backend"| node_translation_backends
node_translation_backends -->|"calls client"| node_openai
node_translation_backends -->|"validates output"| node_validation
node_translation -->|"triages regions"| node_triage
node_translation -->|"uses terms"| node_glossary
node_translation -->|"resolves overrides"| node_overrides
node_paraphrase -.->|"supports backend"| node_mcp
node_render -->|"uses geometry"| node_geometry
node_cli -->|"resumes workspaces"| node_workspace
node_translation_backends -->|"emits events"| node_event_emitter
node_event_emitter -->|"serializes events"| node_events
node_cli -->|"sets output directory"| node_settings
node_translation_backends -->|"selects backend"| node_config

click node_cli "https://github.com/aklid01/manhua/blob/main/pipeline.py"
click node_gui "https://github.com/aklid01/manhua/blob/main/pipeline_gui.py"
click node_import "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage0_import.py"
click node_detection "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage1_detection.py"
click node_ocr "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage2_ocr.py"
click node_translation "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/engine.py"
click node_translation_backends "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/backends.py"
click node_openai "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/_openai_compat.py"
click node_validation "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/translation_validation.py"
click node_triage "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/triage.py"
click node_glossary "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/glossary_series.py"
click node_overrides "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/manual_overrides.py"
click node_paraphrase "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage4_paraphrase.py"
click node_mcp "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/adapters/mcp_server.py"
click node_render "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage5_render/engine.py"
click node_geometry "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage5_render/geometry.py"
click node_qa "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage6_qa.py"
click node_package "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage7_package.py"
click node_touchup "https://github.com/aklid01/manhua/blob/main/touchup/app.py"
click node_workspace "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/workspace.py"
click node_events "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/events.py"
click node_event_emitter "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/event_emitter.py"
click node_settings "https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/settings.py"
click node_config "https://github.com/aklid01/manhua/blob/main/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_import,node_detection,node_ocr toneBlue
class node_translation,node_translation_backends,node_openai,node_validation,node_triage,node_glossary,node_overrides,node_paraphrase,node_mcp toneAmber
class node_render,node_geometry,node_qa,node_package,node_touchup toneMint
class node_cli,node_gui,node_workspace,node_events,node_event_emitter,node_settings,node_config toneRose
class node_reader toneIndigo
```

## Components

### Chapter workflow

- [Chapter import](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage0_import.py): `manhua_pipeline/stages/stage0_import.py`
- [Region detection](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage1_detection.py): `manhua_pipeline/stages/stage1_detection.py`
- [Text OCR](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage2_ocr.py): `manhua_pipeline/stages/stage2_ocr.py`

### Translation and review

- [Literal translation](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/engine.py): `manhua_pipeline/stages/stage3_translation/engine.py`
- [Translation backends](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/backends.py): `manhua_pipeline/stages/stage3_translation/backends.py`
- [OpenAI-compatible client](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/_openai_compat.py): `manhua_pipeline/stages/_openai_compat.py`
- [Translation validation](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/translation_validation.py): `manhua_pipeline/translation_validation.py`
- [Translation triage](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage3_translation/triage.py): `manhua_pipeline/stages/stage3_translation/triage.py`
- [Series glossary](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/glossary_series.py): `manhua_pipeline/io/glossary_series.py`
- [Manual overrides](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/manual_overrides.py): `manhua_pipeline/manual_overrides.py`
- [Dialogue paraphrase](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage4_paraphrase.py): `manhua_pipeline/stages/stage4_paraphrase.py`
- [MCP interface](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/adapters/mcp_server.py): `manhua_pipeline/adapters/mcp_server.py`

### Rendering and quality

- [Page rendering](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage5_render/engine.py): `manhua_pipeline/stages/stage5_render/engine.py`
- [Render geometry](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage5_render/geometry.py): `manhua_pipeline/stages/stage5_render/geometry.py`
- [Quality assurance](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage6_qa.py): `manhua_pipeline/stages/stage6_qa.py`
- [ZIP / CBZ packaging](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/stages/stage7_package.py): `manhua_pipeline/stages/stage7_package.py`
- [Touch-up editor](https://github.com/aklid01/manhua/blob/main/touchup/app.py): `touchup/app.py`

### Workspace and interfaces

- [Pipeline CLI](https://github.com/aklid01/manhua/blob/main/pipeline.py): `pipeline.py`
- [Guided GUI](https://github.com/aklid01/manhua/blob/main/pipeline_gui.py): `pipeline_gui.py`
- [Chapter workspace](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/workspace.py): `manhua_pipeline/io/workspace.py`
- [Pipeline events](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/events.py): `manhua_pipeline/events.py`
- [Event emitter](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/event_emitter.py): `manhua_pipeline/io/event_emitter.py`
- [Runtime settings](https://github.com/aklid01/manhua/blob/main/manhua_pipeline/io/settings.py): `manhua_pipeline/io/settings.py`
- [Pipeline configuration](https://github.com/aklid01/manhua/blob/main/config.py): `config.py`

### Other components

- **Reader / translator**

## Connections

- Reader / translator → Pipeline CLI: runs commands
- Reader / translator → Guided GUI: uses guided flow
- Pipeline CLI → Chapter import: runs stages
- Guided GUI → Touch-up editor: opens editor
- Chapter import → Region detection: next stage
- Region detection → Text OCR: next stage (evidence: `manhua_pipeline/stages/stage1_detection.py`)
- Text OCR → Literal translation: next stage
- Literal translation → Dialogue paraphrase: next stage
- Dialogue paraphrase → Page rendering: next stage
- Page rendering → Quality assurance: next stage
- Quality assurance → ZIP / CBZ packaging: optional packaging
- Literal translation → Translation backends: uses backend (evidence: `manhua_pipeline/stages/stage3_translation/engine.py`)
- Translation backends → OpenAI-compatible client: calls client (evidence: `manhua_pipeline/stages/stage3_translation/backends.py`)
- Translation backends → Translation validation: validates output (evidence: `manhua_pipeline/stages/stage3_translation/backends.py`)
- Literal translation → Translation triage: triages regions (evidence: `manhua_pipeline/stages/stage3_translation/engine.py`)
- Literal translation → Series glossary: uses terms (evidence: `manhua_pipeline/stages/stage3_translation/engine.py`)
- Literal translation → Manual overrides: resolves overrides (evidence: `manhua_pipeline/stages/stage3_translation/engine.py`)
- Dialogue paraphrase → MCP interface: supports backend (evidence: `manhua_pipeline/adapters/mcp_server.py`)
- Page rendering → Render geometry: uses geometry (evidence: `manhua_pipeline/stages/stage5_render/engine.py`)
- Pipeline CLI → Chapter workspace: resumes workspaces (evidence: `pipeline.py`)
- Translation backends → Event emitter: emits events (evidence: `manhua_pipeline/stages/stage3_translation/backends.py`)
- Event emitter → Pipeline events: serializes events (evidence: `manhua_pipeline/io/event_emitter.py`)
- Pipeline CLI → Runtime settings: sets output directory (evidence: `pipeline.py`)
- Translation backends → Pipeline configuration: selects backend (evidence: `config.py`)
