# 0xh4ku/manga-to-epub architecture

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

- Interactive diagram: https://gitdiagram.com/0xh4ku/manga-to-epub
- Repository: https://github.com/0xh4ku/manga-to-epub

## Overview

Manga to EPUB is a fixed-layout manga editor and batch-series workflow, not a general book compressor. Users import a PDF, archive, or image-based EPUB; inspect and adjust spine order, cover behavior, blanks, and pages; then export a validated EPUB for Apple Books. A separate human-reviewed diagnosis workflow finds possible spreads and suggests blank insertions, while series tools manage per-volume edits, presets, project state, and ready-only exports. The graph reflects README-documented capabilities; several controller implementations were not sampled, so uncertain internal call links are omitted.

Main entry points: [`src/manga_pdf_to_epub/gui/layout_app.py`](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_app.py) (Layout workbench), [`src/manga_pdf_to_epub/models/layout.py`](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/models/layout.py) (Layout model), [`src/manga_pdf_to_epub/gui/layout_diagnosis_controller.py`](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_diagnosis_controller.py) (Diagnosis review), [`src/manga_pdf_to_epub/epub/page_factory.py`](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/page_factory.py) (EPUB pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Import and layout"]
  node_layout_gui["Layout workbench<br/>[layout_app.py]"]
  node_source_archive["Archive sources<br/>[archive.py]"]
  node_pdf_extract["PDF extraction"]
  node_layout_model["Layout model<br/>[layout.py]"]
  node_preview["Spread preview"]
  node_layout_edit["Page editing"]
  node_metadata["Book metadata"]
end

subgraph group_diagnosis["Spread diagnosis"]
  node_diagnosis_ui["Diagnosis review"]
  node_diagnosis_view["Diagnosis preview"]
  node_spread_scan["Spread discovery"]
  node_spread_scoring["Spread scoring<br/>[pair_scoring.py]"]
  node_insert_scoring["Insert scoring<br/>[scoring.py]"]
end

subgraph group_series["Series workflow"]
  node_series_ui["Series management"]
  node_series_workflow["Series export"]
  node_series_model["Series project<br/>[series.py]"]
end

subgraph group_export["EPUB output"]
  node_epub_cli["Lossless CLI"]
  node_page_factory["EPUB pages<br/>[page_factory.py]"]
  node_epub_writer["EPUB writer<br/>[writer.py]"]
  node_epub_validate["EPUB validation<br/>[validation.py]"]
end

node_reader(("Manga editor"))
node_source_files["Source files"]
node_epub_file["Fixed-layout EPUB"]
node_books(("Apple Books"))

node_reader -->|"opens editor"| node_layout_gui
node_source_files -->|"selects source"| node_layout_gui
node_layout_gui -->|"loads archives"| node_source_archive
node_layout_gui -->|"loads PDF pages"| node_pdf_extract
node_source_archive -->|"provides pages"| node_layout_model
node_pdf_extract -->|"provides images"| node_layout_model
node_layout_gui -->|"manages layout"| node_layout_model
node_layout_gui -->|"refreshes preview"| node_preview
node_layout_gui -->|"dispatches edits"| node_layout_edit
node_layout_gui -->|"edits metadata"| node_metadata
node_layout_model -->|"supplies pages"| node_preview
node_layout_edit -->|"changes spine"| node_layout_model
node_reader -->|"reviews spreads"| node_diagnosis_ui
node_diagnosis_ui -->|"requests scan"| node_spread_scan
node_spread_scan -->|"scores pairs"| node_spread_scoring
node_diagnosis_ui -->|"requests suggestions"| node_insert_scoring
node_diagnosis_ui -->|"shows review"| node_diagnosis_view
node_diagnosis_ui -->|"inserts blank"| node_layout_model
node_reader -->|"manages volumes"| node_series_ui
node_series_ui -->|"updates project"| node_series_model
node_series_ui -->|"starts export"| node_series_workflow
node_series_workflow -->|"uses volume layout"| node_layout_model
node_reader -->|"runs conversion"| node_epub_cli
node_source_files -->|"provides input"| node_epub_cli
node_layout_gui -->|"builds EPUB pages"| node_page_factory
node_epub_cli -->|"builds EPUB pages"| node_page_factory
node_metadata -->|"supplies metadata"| node_page_factory
node_page_factory -->|"provides book items"| node_epub_writer
node_epub_writer -->|"validates output"| node_epub_validate
node_epub_validate -->|"reports valid EPUB"| node_epub_file
node_epub_file -->|"opens for reading"| node_books

click node_layout_gui "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_app.py"
click node_source_archive "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/sources/archive.py"
click node_pdf_extract "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/pdf/image_extraction.py"
click node_layout_model "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/models/layout.py"
click node_preview "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_preview_controller.py"
click node_layout_edit "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_edit_controller.py"
click node_metadata "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_inspector_controller.py"
click node_diagnosis_ui "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_diagnosis_controller.py"
click node_diagnosis_view "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_diagnosis_view_controller.py"
click node_spread_scan "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/spread_continuity/scan_pdf_adjacent.py"
click node_spread_scoring "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/spread_continuity/lib/scoring/pair_scoring.py"
click node_insert_scoring "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/insert_point_scorer/scoring.py"
click node_series_ui "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_series_controller.py"
click node_series_workflow "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_series_workflow.py"
click node_series_model "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/models/series.py"
click node_epub_cli "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/cli/pdf_to_epub_lossless.py"
click node_page_factory "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/page_factory.py"
click node_epub_writer "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/writer.py"
click node_epub_validate "https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/validation.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_layout_gui,node_source_archive,node_pdf_extract,node_layout_model,node_preview,node_layout_edit,node_metadata toneBlue
class node_diagnosis_ui,node_diagnosis_view,node_spread_scan,node_spread_scoring,node_insert_scoring toneAmber
class node_series_ui,node_series_workflow,node_series_model toneMint
class node_epub_cli,node_page_factory,node_epub_writer,node_epub_validate toneRose
class node_reader,node_source_files,node_epub_file,node_books toneIndigo
```

## Components

### Import and layout

- [Layout workbench](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_app.py): `src/manga_pdf_to_epub/gui/layout_app.py`
- [Archive sources](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/sources/archive.py): `src/manga_pdf_to_epub/sources/archive.py`
- [PDF extraction](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/pdf/image_extraction.py): `src/manga_pdf_to_epub/pdf/image_extraction.py`
- [Layout model](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/models/layout.py): `src/manga_pdf_to_epub/models/layout.py`
- [Spread preview](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_preview_controller.py): `src/manga_pdf_to_epub/gui/layout_preview_controller.py`
- [Page editing](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_edit_controller.py): `src/manga_pdf_to_epub/gui/layout_edit_controller.py`
- [Book metadata](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_inspector_controller.py): `src/manga_pdf_to_epub/gui/layout_inspector_controller.py`

### Spread diagnosis

- [Diagnosis review](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_diagnosis_controller.py): `src/manga_pdf_to_epub/gui/layout_diagnosis_controller.py`
- [Diagnosis preview](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_diagnosis_view_controller.py): `src/manga_pdf_to_epub/gui/layout_diagnosis_view_controller.py`
- [Spread discovery](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/spread_continuity/scan_pdf_adjacent.py): `src/manga_pdf_to_epub/diagnosis/spread_continuity/scan_pdf_adjacent.py`
- [Spread scoring](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/spread_continuity/lib/scoring/pair_scoring.py): `src/manga_pdf_to_epub/diagnosis/spread_continuity/lib/scoring/pair_scoring.py`
- [Insert scoring](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/diagnosis/insert_point_scorer/scoring.py): `src/manga_pdf_to_epub/diagnosis/insert_point_scorer/scoring.py`

### Series workflow

- [Series management](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_series_controller.py): `src/manga_pdf_to_epub/gui/layout_series_controller.py`
- [Series export](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/gui/layout_series_workflow.py): `src/manga_pdf_to_epub/gui/layout_series_workflow.py`
- [Series project](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/models/series.py): `src/manga_pdf_to_epub/models/series.py`

### EPUB output

- [Lossless CLI](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/cli/pdf_to_epub_lossless.py): `src/manga_pdf_to_epub/cli/pdf_to_epub_lossless.py`
- [EPUB pages](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/page_factory.py): `src/manga_pdf_to_epub/epub/page_factory.py`
- [EPUB writer](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/writer.py): `src/manga_pdf_to_epub/epub/writer.py`
- [EPUB validation](https://github.com/0xh4ku/manga-to-epub/blob/main/src/manga_pdf_to_epub/epub/validation.py): `src/manga_pdf_to_epub/epub/validation.py`

### Other components

- **Manga editor**
- **Source files**
- **Fixed-layout EPUB**
- **Apple Books**

## Connections

- Manga editor → Layout workbench: opens editor
- Source files → Layout workbench: selects source
- Layout workbench → Archive sources: loads archives
- Layout workbench → PDF extraction: loads PDF pages
- Archive sources → Layout model: provides pages
- PDF extraction → Layout model: provides images
- Layout workbench → Layout model: manages layout
- Layout workbench → Spread preview: refreshes preview
- Layout workbench → Page editing: dispatches edits
- Layout workbench → Book metadata: edits metadata
- Layout model → Spread preview: supplies pages
- Page editing → Layout model: changes spine
- Manga editor → Diagnosis review: reviews spreads
- Diagnosis review → Spread discovery: requests scan
- Spread discovery → Spread scoring: scores pairs
- Diagnosis review → Insert scoring: requests suggestions
- Diagnosis review → Diagnosis preview: shows review
- Diagnosis review → Layout model: inserts blank
- Manga editor → Series management: manages volumes
- Series management → Series project: updates project
- Series management → Series export: starts export
- Series export → Layout model: uses volume layout
- Manga editor → Lossless CLI: runs conversion
- Source files → Lossless CLI: provides input
- Layout workbench → EPUB pages: builds EPUB pages
- Lossless CLI → EPUB pages: builds EPUB pages
- Book metadata → EPUB pages: supplies metadata
- EPUB pages → EPUB writer: provides book items
- EPUB writer → EPUB validation: validates output
- EPUB validation → Fixed-layout EPUB: reports valid EPUB
- Fixed-layout EPUB → Apple Books: opens for reading