# xiebingqiang/glossbook architecture

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

- Interactive diagram: https://gitdiagram.com/xiebingqiang/glossbook
- Repository: https://github.com/xiebingqiang/glossbook

## Overview

glossbook turns an EPUB into a language-learning edition: the CLI reads and selects chapters, generates or reuses translations and annotations, then renders them into an EPUB with ruby glosses, popup notes, and optional chapter guides. Preview, cache-only rebuild, inspection, and usage reporting are additional user workflows. The sampled excerpts show key boundaries; some CLI-to-module wiring and unsampled feature implementations are represented only where the README or module descriptions support them.

Main entry points: [`glossbook/cli.py`](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/cli.py) (CLI commands), [`glossbook/pipeline.py`](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/pipeline.py) (Generation pipeline), [`glossbook/render.py`](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/render.py) (Notes and ruby rendering), [`glossbook/llm.py`](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/llm.py) (Model client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_settings["Settings and models<br/>[config.py]"]
end

subgraph group_analysis["EPUB analysis"]
  node_epub_input["EPUB loader<br/>[epub.py]"]
  node_chaptering["Chapter selection<br/>[chapters.py]"]
  node_language["Language detection<br/>[detect.py]"]
  node_segmentation["Text segmentation<br/>[segment.py]"]
end

subgraph group_generation["Annotation generation"]
  node_pipeline["Generation pipeline<br/>[pipeline.py]"]
  node_prompts["Annotation prompts<br/>[prompt.py]"]
  node_model_client["Model client<br/>[llm.py]"]
  node_cache[("Request cache<br/>[pipeline.py]")]
  node_usage["Usage and estimates<br/>[usage.py]"]
  node_matching["Gloss matching<br/>[match.py]"]
end

subgraph group_output["Preview and publishing"]
  node_placement["Gloss placement<br/>[placement.py]"]
  node_textnodes["XHTML text editing<br/>[textnodes.py]"]
  node_render["Notes and ruby rendering<br/>[render.py]"]
  node_preview["Interactive HTML preview<br/>[preview.py]"]
  node_packager["EPUB packaging<br/>[package.py]"]
end

node_reader(("Reader"))
node_api{{"OpenAI-compatible API"}}
node_output_epub["Annotated EPUB"]

node_reader -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"opens book"| node_epub_input
node_cli -->|"selects chapters"| node_chaptering
node_cli -->|"checks language"| node_language
node_epub_input -->|"provides book structure"| node_chaptering
node_cli -->|"runs generation"| node_pipeline
node_pipeline -->|"splits text"| node_segmentation
node_pipeline -->|"builds requests"| node_prompts
node_pipeline -->|"reads and writes"| node_cache
node_pipeline -->|"dispatches requests"| node_model_client
node_model_client -.->|"sends completions"| node_api
node_pipeline -->|"validates glosses"| node_matching
node_model_client -->|"records usage"| node_usage
node_cli -->|"estimates and reports"| node_usage
node_cli -->|"prepares glosses"| node_placement
node_placement -->|"matches expressions"| node_matching
node_cli -->|"renders annotations"| node_render
node_render -->|"uses placements"| node_placement
node_render -->|"edits XHTML"| node_textnodes
node_cli -->|"builds preview"| node_preview
node_preview -->|"renders variants"| node_render
node_cli -->|"writes book"| node_packager
node_packager -->|"creates EPUB"| node_output_epub
node_reader -->|"reads edition"| node_output_epub

click node_cli "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/cli.py"
click node_settings "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/config.py"
click node_epub_input "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/epub.py"
click node_chaptering "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/chapters.py"
click node_language "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/detect.py"
click node_segmentation "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/segment.py"
click node_pipeline "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/pipeline.py"
click node_prompts "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/prompt.py"
click node_model_client "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/llm.py"
click node_cache "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/pipeline.py"
click node_usage "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/usage.py"
click node_matching "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/match.py"
click node_placement "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/placement.py"
click node_textnodes "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/textnodes.py"
click node_render "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/render.py"
click node_preview "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/preview.py"
click node_packager "https://github.com/xiebingqiang/glossbook/blob/main/glossbook/package.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_settings toneBlue
class node_epub_input,node_chaptering,node_language,node_segmentation toneAmber
class node_pipeline,node_prompts,node_model_client,node_cache,node_usage,node_matching,node_api toneMint
class node_placement,node_textnodes,node_render,node_preview,node_packager toneRose
class node_reader,node_output_epub toneIndigo
```

## Components

### Command interface

- [CLI commands](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/cli.py): `glossbook/cli.py`
- [Settings and models](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/config.py): `glossbook/config.py`

### EPUB analysis

- [EPUB loader](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/epub.py): `glossbook/epub.py`
- [Chapter selection](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/chapters.py): `glossbook/chapters.py`
- [Language detection](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/detect.py): `glossbook/detect.py`
- [Text segmentation](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/segment.py): `glossbook/segment.py`

### Annotation generation

- [Generation pipeline](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/pipeline.py): `glossbook/pipeline.py`
- [Annotation prompts](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/prompt.py): `glossbook/prompt.py`
- [Model client](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/llm.py): `glossbook/llm.py`
- [Request cache](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/pipeline.py): `glossbook/pipeline.py`
- [Usage and estimates](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/usage.py): `glossbook/usage.py`
- [Gloss matching](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/match.py): `glossbook/match.py`

### Preview and publishing

- [Gloss placement](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/placement.py): `glossbook/placement.py`
- [XHTML text editing](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/textnodes.py): `glossbook/textnodes.py`
- [Notes and ruby rendering](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/render.py): `glossbook/render.py`
- [Interactive HTML preview](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/preview.py): `glossbook/preview.py`
- [EPUB packaging](https://github.com/xiebingqiang/glossbook/blob/main/glossbook/package.py): `glossbook/package.py`

### Other components

- **Reader**
- **OpenAI-compatible API**
- **Annotated EPUB**

## Connections

- Reader → CLI commands: runs commands
- CLI commands → Settings and models: loads settings
- CLI commands → EPUB loader: opens book
- CLI commands → Chapter selection: selects chapters
- CLI commands → Language detection: checks language
- EPUB loader → Chapter selection: provides book structure
- CLI commands → Generation pipeline: runs generation
- Generation pipeline → Text segmentation: splits text
- Generation pipeline → Annotation prompts: builds requests
- Generation pipeline → Request cache: reads and writes
- Generation pipeline → Model client: dispatches requests
- Model client → OpenAI-compatible API: sends completions
- Generation pipeline → Gloss matching: validates glosses
- Model client → Usage and estimates: records usage
- CLI commands → Usage and estimates: estimates and reports
- CLI commands → Gloss placement: prepares glosses
- Gloss placement → Gloss matching: matches expressions
- CLI commands → Notes and ruby rendering: renders annotations
- Notes and ruby rendering → Gloss placement: uses placements
- Notes and ruby rendering → XHTML text editing: edits XHTML
- CLI commands → Interactive HTML preview: builds preview
- Interactive HTML preview → Notes and ruby rendering: renders variants
- CLI commands → EPUB packaging: writes book
- EPUB packaging → Annotated EPUB: creates EPUB
- Reader → Annotated EPUB: reads edition