# kovidgoyal/calibre architecture

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

- Interactive diagram: https://gitdiagram.com/kovidgoyal/calibre
- Repository: https://github.com/kovidgoyal/calibre

## Overview

calibre is a cross-platform e-book manager. Its main user workflow is to add books to a library, enrich their metadata, convert or edit them, and read them or transfer them to an e-reader. The README also identifies web metadata lookup, newspaper downloads, and device communication as product capabilities. The graph combines those documented stages with sampled GUI, scraper, and shared-runtime modules; unsampled capability links are grounded in the README rather than inferred from implementation details.

Main entry points: [`src/calibre/gui2/__init__.py`](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/__init__.py) (Desktop GUI), [`src/calibre/scraper/webengine_backend.py`](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/scraper/webengine_backend.py) (Browser backend), [`src/qt/core.py`](https://github.com/kovidgoyal/calibre/blob/master/src/qt/core.py) (Qt bindings), [`src/calibre/ebooks/metadata/sources/search_engines.py`](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/ebooks/metadata/sources/search_engines.py) (Metadata search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["User applications"]
  node_gui["Desktop GUI<br/>[__init__.py]"]
  node_viewer["Book viewer"]
  node_server["Content server<br/>[routes.py]"]
end

subgraph group_books["Book workflows"]
  node_library[("Book catalog")]
  node_metadata["Metadata tools"]
  node_conversion["Format conversion"]
  node_polish["E-book editing"]
  node_news["News downloads"]
end

subgraph group_connect["External connections"]
  node_device["Reader devices"]
  node_metadata_sources["Metadata search<br/>[search_engines.py]"]
  node_web(("Web sources"))
  node_scraper["Web scraper<br/>[qt.py]"]
  node_scraper_backend["Browser backend"]
end

subgraph group_runtime["Shared runtime"]
  node_web_bridge["WebEngine bridge<br/>[webengine.py]"]
  node_preferences["Preferences and config"]
  node_localization["Localization<br/>[localization.py]"]
  node_widgets["GUI widgets<br/>[widgets.py]"]
  node_qt["Qt bindings<br/>[core.py]"]
  node_prints["Output utilities<br/>[prints.py]"]
end

node_user(("Reader"))
node_reader_device(("E-book reader"))
node_web_content(("Scraped sites"))

node_user -->|"uses"| node_gui
node_gui -.->|"manages books"| node_library
node_gui -.->|"fetches metadata"| node_metadata
node_gui -.->|"converts books"| node_conversion
node_gui -.->|"edits books"| node_polish
node_gui -.->|"views books"| node_viewer
node_gui -.->|"downloads news"| node_news
node_gui -.->|"communicates with"| node_device
node_metadata_sources -.->|"searches"| node_web
node_gui -.->|"serves books"| node_server
node_device -.->|"transfers books"| node_reader_device
node_scraper -->|"dispatches to"| node_scraper_backend
node_scraper_backend -.->|"fetches pages"| node_web_content
node_scraper_backend -.->|"uses bridge"| node_web_bridge
node_gui -.->|"uses widgets"| node_widgets
node_gui -->|"loads config"| node_preferences
node_gui -->|"uses translations"| node_localization
node_gui -->|"uses Qt"| node_qt
node_scraper_backend -->|"uses Qt"| node_qt
node_web_bridge -->|"uses Qt"| node_qt
node_metadata_sources -->|"logs output"| node_prints

click node_gui "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/__init__.py"
click node_viewer "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/gui2/viewer"
click node_library "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/db"
click node_metadata "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/metadata"
click node_conversion "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/conversion"
click node_polish "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/oeb/polish"
click node_news "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/conversion"
click node_device "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices"
click node_metadata_sources "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/ebooks/metadata/sources/search_engines.py"
click node_scraper "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/scraper/qt.py"
click node_scraper_backend "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/scraper/webengine_backend.py"
click node_web_bridge "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/utils/webengine.py"
click node_preferences "https://github.com/kovidgoyal/calibre/tree/master/src/calibre/utils"
click node_localization "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/utils/localization.py"
click node_widgets "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/widgets.py"
click node_qt "https://github.com/kovidgoyal/calibre/blob/master/src/qt/core.py"
click node_prints "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/prints.py"
click node_server "https://github.com/kovidgoyal/calibre/blob/master/src/calibre/srv/routes.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_gui,node_viewer,node_server toneBlue
class node_library,node_metadata,node_conversion,node_polish,node_news toneAmber
class node_device,node_metadata_sources,node_web,node_scraper,node_scraper_backend toneMint
class node_web_bridge,node_preferences,node_localization,node_widgets,node_qt,node_prints toneRose
class node_user,node_reader_device,node_web_content toneIndigo
```

## Components

### User applications

- [Desktop GUI](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/__init__.py): `src/calibre/gui2/__init__.py`
- [Book viewer](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/gui2/viewer): `src/calibre/gui2/viewer`
- [Content server](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/srv/routes.py): `src/calibre/srv/routes.py`

### Book workflows

- [Book catalog](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/db): `src/calibre/db`
- [Metadata tools](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/metadata): `src/calibre/ebooks/metadata`
- [Format conversion](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/conversion): `src/calibre/ebooks/conversion`
- [E-book editing](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/oeb/polish): `src/calibre/ebooks/oeb/polish`
- [News downloads](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/ebooks/conversion): `src/calibre/ebooks/conversion`

### External connections

- [Reader devices](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices): `src/calibre/devices`
- [Metadata search](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/ebooks/metadata/sources/search_engines.py): `src/calibre/ebooks/metadata/sources/search_engines.py`
- **Web sources**
- [Web scraper](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/scraper/qt.py): `src/calibre/scraper/qt.py`
- [Browser backend](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/scraper/webengine_backend.py): `src/calibre/scraper/webengine_backend.py`

### Shared runtime

- [WebEngine bridge](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/utils/webengine.py): `src/calibre/utils/webengine.py`
- [Preferences and config](https://github.com/kovidgoyal/calibre/tree/master/src/calibre/utils): `src/calibre/utils`
- [Localization](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/utils/localization.py): `src/calibre/utils/localization.py`
- [GUI widgets](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/widgets.py): `src/calibre/gui2/widgets.py`
- [Qt bindings](https://github.com/kovidgoyal/calibre/blob/master/src/qt/core.py): `src/qt/core.py`
- [Output utilities](https://github.com/kovidgoyal/calibre/blob/master/src/calibre/prints.py): `src/calibre/prints.py`

### Other components

- **Reader**
- **E-book reader**
- **Scraped sites**

## Connections

- Reader → Desktop GUI: uses
- Desktop GUI → Book catalog: manages books
- Desktop GUI → Metadata tools: fetches metadata (evidence: `src/calibre/gui2/__init__.py`)
- Desktop GUI → Format conversion: converts books
- Desktop GUI → E-book editing: edits books
- Desktop GUI → Book viewer: views books
- Desktop GUI → News downloads: downloads news
- Desktop GUI → Reader devices: communicates with
- Metadata search → Web sources: searches
- Desktop GUI → Content server: serves books
- Reader devices → E-book reader: transfers books
- Web scraper → Browser backend: dispatches to (evidence: `src/calibre/scraper/qt.py`)
- Browser backend → Scraped sites: fetches pages
- Browser backend → WebEngine bridge: uses bridge (evidence: `src/calibre/scraper/webengine_backend.py`)
- Desktop GUI → GUI widgets: uses widgets (evidence: `src/calibre/gui2/__init__.py`)
- Desktop GUI → Preferences and config: loads config (evidence: `src/calibre/gui2/__init__.py`)
- Desktop GUI → Localization: uses translations (evidence: `src/calibre/gui2/__init__.py`)
- Desktop GUI → Qt bindings: uses Qt (evidence: `src/calibre/gui2/__init__.py`)
- Browser backend → Qt bindings: uses Qt (evidence: `src/calibre/scraper/webengine_backend.py`)
- WebEngine bridge → Qt bindings: uses Qt (evidence: `src/calibre/utils/webengine.py`)
- Metadata search → Output utilities: logs output (evidence: `src/calibre/ebooks/metadata/sources/search_engines.py`)
