# phuc-nt/scan-to-ebook architecture

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

- Interactive diagram: https://gitdiagram.com/phuc-nt/scan-to-ebook
- Repository: https://github.com/phuc-nt/scan-to-ebook

## Overview

scan-to-ebook turns scans, PDFs, and Drive sources into either OCR-based prose EPUBs or offline manga EPUB3s. The prose workflow prepares pages, gathers book context, OCRs pages, merges and cleans Markdown, then builds an EPUB; users can also verify outputs and track OCR costs. Manga follows a separate image-import-to-fixed-layout workflow. The graph reflects README capabilities and sampled orchestration; some links for documented but unsampled features are omitted where call ownership is unclear.

Main entry points: [`src/scan_to_ebook/cli.py`](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/cli.py) (CLI commands), [`src/scan_to_ebook/pipeline.py`](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/pipeline.py) (Prose coordinator), [`src/scan_to_ebook/manga_pipeline.py`](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/manga_pipeline.py) (Manga coordinator), [`src/scan_to_ebook/drive_input.py`](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/drive_input.py) (Drive input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_pipeline["Prose coordinator<br/>[pipeline.py]"]
  node_manga_pipeline["Manga coordinator<br/>[manga_pipeline.py]"]
end

subgraph group_inputs["Input preparation"]
  node_drive_input["Drive input<br/>[drive_input.py]"]
  node_drive_download["Drive downloader<br/>[drive_download.py]"]
  node_pdf_render["PDF renderer<br/>[pdf_render.py]"]
  node_image_ops["Image preparation<br/>[image_ops.py]"]
  node_archive_extract["Archive extraction<br/>[archive_extract.py]"]
  node_mobi_extract["MOBI extraction<br/>[mobi_extract.py]"]
end

subgraph group_prose["Prose OCR workflow"]
  node_context["Book context prepass<br/>[context_prepass.py]"]
  node_ocr["Page OCR<br/>[ocr.py]"]
  node_post["Text post-processing<br/>[post_process.py]"]
  node_epub_build["Prose EPUB builder<br/>[epub_build.py]"]
  node_epub_verify["EPUB verification<br/>[epub_verify.py]"]
end

subgraph group_manga["Manga workflow"]
  node_fixed_layout["Fixed-layout builder"]
  node_cover_detect["Manga cover detection"]
end

subgraph group_services["State and integrations"]
  node_cost_ledger[("Cost ledger<br/>[cost_ledger.py]")]
  node_openrouter["OpenRouter vision API"]
  node_pandoc["pandoc"]
  node_google_drive["Google Drive"]
end

node_user(("Book creator"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches prose"| node_pipeline
node_cli -->|"dispatches manga"| node_manga_pipeline
node_pipeline -->|"runs prepass"| node_context
node_pipeline -->|"runs OCR"| node_ocr
node_pipeline -->|"processes text"| node_post
node_pipeline -->|"builds EPUB"| node_epub_build
node_pipeline -->|"records costs"| node_cost_ledger
node_cli -->|"verifies EPUB"| node_epub_verify
node_context -->|"requests context"| node_openrouter
node_ocr -->|"requests OCR"| node_openrouter
node_epub_build -->|"converts Markdown"| node_pandoc
node_cli -->|"renders PDF"| node_pdf_render
node_cli -->|"imports images"| node_image_ops
node_manga_pipeline -->|"imports Drive"| node_drive_input
node_drive_input -->|"downloads files"| node_drive_download
node_drive_download -->|"fetches source"| node_google_drive
node_manga_pipeline -->|"extracts archives"| node_archive_extract
node_manga_pipeline -->|"extracts MOBI"| node_mobi_extract
node_manga_pipeline -->|"builds EPUB3"| node_fixed_layout
node_manga_pipeline -.->|"detects cover"| node_cover_detect
node_cover_detect -.->|"requests detection"| node_openrouter

click node_cli "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/cli.py"
click node_pipeline "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/pipeline.py"
click node_manga_pipeline "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/manga_pipeline.py"
click node_drive_input "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/drive_input.py"
click node_drive_download "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/drive_download.py"
click node_pdf_render "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/pdf_render.py"
click node_image_ops "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/image_ops.py"
click node_archive_extract "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/archive_extract.py"
click node_mobi_extract "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/mobi_extract.py"
click node_context "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/context_prepass.py"
click node_ocr "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/ocr.py"
click node_post "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/post_process.py"
click node_epub_build "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub_build.py"
click node_epub_verify "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub_verify.py"
click node_fixed_layout "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub3_fixed_layout.py"
click node_cover_detect "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/manga_cover_detect.py"
click node_cost_ledger "https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/cost_ledger.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_cli,node_pipeline,node_manga_pipeline toneBlue
class node_drive_input,node_drive_download,node_pdf_render,node_image_ops,node_archive_extract,node_mobi_extract toneAmber
class node_context,node_ocr,node_post,node_epub_build,node_epub_verify toneMint
class node_fixed_layout,node_cover_detect toneRose
class node_cost_ledger,node_openrouter,node_pandoc,node_google_drive,node_user toneIndigo
```

## Components

### CLI and orchestration

- [CLI commands](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/cli.py): `src/scan_to_ebook/cli.py`
- [Prose coordinator](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/pipeline.py): `src/scan_to_ebook/pipeline.py`
- [Manga coordinator](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/manga_pipeline.py): `src/scan_to_ebook/manga_pipeline.py`

### Input preparation

- [Drive input](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/drive_input.py): `src/scan_to_ebook/drive_input.py`
- [Drive downloader](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/drive_download.py): `src/scan_to_ebook/drive_download.py`
- [PDF renderer](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/pdf_render.py): `src/scan_to_ebook/pdf_render.py`
- [Image preparation](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/image_ops.py): `src/scan_to_ebook/image_ops.py`
- [Archive extraction](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/archive_extract.py): `src/scan_to_ebook/archive_extract.py`
- [MOBI extraction](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/mobi_extract.py): `src/scan_to_ebook/mobi_extract.py`

### Prose OCR workflow

- [Book context prepass](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/context_prepass.py): `src/scan_to_ebook/context_prepass.py`
- [Page OCR](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/ocr.py): `src/scan_to_ebook/ocr.py`
- [Text post-processing](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/post_process.py): `src/scan_to_ebook/post_process.py`
- [Prose EPUB builder](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub_build.py): `src/scan_to_ebook/epub_build.py`
- [EPUB verification](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub_verify.py): `src/scan_to_ebook/epub_verify.py`

### Manga workflow

- [Fixed-layout builder](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/epub3_fixed_layout.py): `src/scan_to_ebook/epub3_fixed_layout.py`
- [Manga cover detection](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/manga_cover_detect.py): `src/scan_to_ebook/manga_cover_detect.py`

### State and integrations

- [Cost ledger](https://github.com/phuc-nt/scan-to-ebook/blob/main/src/scan_to_ebook/cost_ledger.py): `src/scan_to_ebook/cost_ledger.py`
- **OpenRouter vision API**
- **pandoc**
- **Google Drive**

### Other components

- **Book creator**

## Connections

- Book creator → CLI commands: runs commands
- CLI commands → Prose coordinator: dispatches prose
- CLI commands → Manga coordinator: dispatches manga
- Prose coordinator → Book context prepass: runs prepass
- Prose coordinator → Page OCR: runs OCR
- Prose coordinator → Text post-processing: processes text
- Prose coordinator → Prose EPUB builder: builds EPUB
- Prose coordinator → Cost ledger: records costs
- CLI commands → EPUB verification: verifies EPUB
- Book context prepass → OpenRouter vision API: requests context
- Page OCR → OpenRouter vision API: requests OCR
- Prose EPUB builder → pandoc: converts Markdown
- CLI commands → PDF renderer: renders PDF
- CLI commands → Image preparation: imports images
- Manga coordinator → Drive input: imports Drive
- Drive input → Drive downloader: downloads files
- Drive downloader → Google Drive: fetches source
- Manga coordinator → Archive extraction: extracts archives
- Manga coordinator → MOBI extraction: extracts MOBI
- Manga coordinator → Fixed-layout builder: builds EPUB3
- Manga coordinator → Manga cover detection: detects cover
- Manga cover detection → OpenRouter vision API: requests detection