# janeczku/calibre-web architecture

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

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

## Overview

##### Project Type and Purpose
- Calibre-Web is a full-stack web application that provides an intuitive interface for browsing, reading, and managing eBooks stored in a Calibre database.
- The system integrates various functionalities: user management (including OAuth, LDAP, and “Magic Link” login), metadata management and editing, eBook conversion (using Calibre binaries), reading support for multiple eBook formats, and additional integrations (Google Drive, Kobo syncing, etc.).

##### Main Components
a. Frontend / User Interface:
- HTML5 and Bootstrap-based user interfaces.
- Templates stored under the “cps/templates” directory.
- Static resources (CSS, JavaScript, images, fonts, locale files) located in “cps/static” and “cps/locale.”
- Translation and localization support (multiple languages and i18n files under “cps/translations”).

b. Backend / Business Logic:
- The core Python modules within the “cps” package that handle various aspects of the application:
- User authentication and session management (e.g., cw_login, MyLoginManager.py, remotelogin.py).
- Routing and request handling (e.g., server.py, web.py, tornado_wsgi.py and gevent_wsgi.py).
- Book and metadata handling (e.g., comic.py, basic.py, epub.py, metadata_provider for different sources).
- Services and scheduled tasks (modules under cps/services and cps/tasks) for background processes like metadata backup, mail tasks, thumbnail generation, and worker processes.
- Utility modules (e.g., helper.py, logger.py, cache_buster.py) that support various functionality.
- External integrations for Calibre conversion commands, Google Drive support, and Kobo device syncing.

c. Data Persistence:
- Usage of the Calibre database (“library/metadata.db”) as the core data store.
- Configuration management files (e.g., cps/config_sql.py, and configuration in the README for database and optional binary paths).

d. External Services and Dependencies:
- Calibre binaries (ebook conversion tools) and associated external applications (for instance, ghostscript and ImageMagick).
- Docker integration options for containerized deployments of Calibre-Web.
- External authentication services (Google, GitHub, LDAP) and Google Drive integration.

##### Architectural Patterns and Design Principles
- The application follows a robust layered architecture separating presentation (templates, static assets) from business logic (backend Python modules) and utility services (tasks, external integrations).
- A Model-View-Controller (MVC) style can be inferred:
- “Views” are represented by templates and static web assets.
- “Controllers” or route-handlers are in modules such as server.py, web.py, and tornado_wsgi.py.
- “Models” correlate to data management with the Calibre database and the metadata-related modules.
- Extensive use of modularization is seen with the “cps” package (with sub-packages for login, adapters, services, tasks) which aids in a micro-modular design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        Browser["Web Browser"]:::ui
        Templates["Templates"]:::ui
        Static["Static Assets"]:::ui
        LocaleStatic["Locale Files (Static)"]:::ui
        Translations["Translations"]:::ui
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Core["Core Python Modules (cps)"]:::backend
        
        subgraph "Routing & Request Handling"
            Server["server.py"]:::backend
            Web["web.py"]:::backend
            Tornado["tornado_wsgi.py"]:::backend
            Gevent["gevent_wsgi.py"]:::backend
        end

        subgraph "Authentication"
            CWLogin["cw_login"]:::backend
            LoginManager["MyLoginManager.py"]:::backend
            RemoteLogin["remotelogin.py"]:::backend
        end

        subgraph "eBook & Metadata Management"
            Basic["basic.py"]:::backend
            Comic["comic.py"]:::backend
            EPUB["epub.py"]:::backend
            MetaProvider["metadata_provider"]:::backend
        end

        subgraph "Background Tasks & Services"
            Tasks["tasks"]:::backend
            Services["services"]:::backend
        end

        subgraph "Utilities"
            Helper["helper.py"]:::backend
            Logger["logger.py"]:::backend
            CacheBuster["cache_buster.py"]:::backend
            FileHelper["file_helper.py"]:::backend
        end
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        CalibreDB["Calibre Database"]:::data
        Config["Configuration"]:::data
    end

    %% External Integrations
    subgraph "External Integrations"
        subgraph "Calibre Conversion"
            Converter["converter.py"]:::external
            Subproc["subproc_wrapper.py"]:::external
        end
        subgraph "Google Drive Integration"
            GDrive["gdrive.py"]:::external
            GDriveUtils["gdriveutils.py"]:::external
        end
        subgraph "Kobo Syncing"
            Kobo["kobo"]:::external
            KoboAuth["kobo_auth.py"]:::external
            KoboSync["kobo_sync_status.py"]:::external
        end
        subgraph "OAuth/External Auth"
            OAuth["oauth.py"]:::external
            OAuthBB["oauth_bb.py"]:::external
        end
    end

    %% Connections between UI components
    Browser --> Templates
    Browser --> Static
    Browser --> LocaleStatic
    Browser --> Translations

    %% Interaction from Browser to Backend Routing
    Browser -->|"HTTP Request"| Server

    %% Backend Core connecting to submodules
    Core --> Server
    Core --> CWLogin
    Core --> Basic
    Core --> Tasks
    Core --> Helper

    %% Routing to Authentication and eBook Management
    Server -->|"handles_auth"| CWLogin
    Server -->|"handles_request"| Basic

    %% Authentication interactions with External Auth
    CWLogin -->|"triggers"| OAuth
    LoginManager -->|"triggers"| OAuthBB

    %% eBook Management interactions with Data Persistence and External Integrations
    Basic -->|"reads/writes"| CalibreDB
    Tasks -->|"updates"| CalibreDB
    Basic -->|"converts_ebooks"| Converter
    Basic -->|"syncs_drive"| GDrive
    Basic -->|"syncs_device"| Kobo

    %% Optional interaction between Background Services and eBook Management
    Services -->|"calls"| Basic

    %% Class definitions for styling
    classDef ui fill:#AED6F1,stroke:#3498DB,stroke-width:2px
    classDef backend fill:#A9DFBF,stroke:#27AE60,stroke-width:2px
    classDef data fill:#F9E79F,stroke:#F1C40F,stroke-width:2px
    classDef external fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px

    %% Click Events - Frontend / User Interface
    click Templates "https://github.com/janeczku/calibre-web/tree/master/cps/templates"
    click Static "https://github.com/janeczku/calibre-web/tree/master/cps/static"
    click LocaleStatic "https://github.com/janeczku/calibre-web/tree/master/cps/static/locale"
    click Translations "https://github.com/janeczku/calibre-web/tree/master/cps/translations"

    %% Click Events - Backend / Business Logic
    click Core "https://github.com/janeczku/calibre-web/tree/master/cps"
    click Server "https://github.com/janeczku/calibre-web/blob/master/cps/server.py"
    click Web "https://github.com/janeczku/calibre-web/blob/master/cps/web.py"
    click Tornado "https://github.com/janeczku/calibre-web/blob/master/cps/tornado_wsgi.py"
    click Gevent "https://github.com/janeczku/calibre-web/blob/master/cps/gevent_wsgi.py"
    click CWLogin "https://github.com/janeczku/calibre-web/tree/master/cps/cw_login"
    click LoginManager "https://github.com/janeczku/calibre-web/blob/master/cps/MyLoginManager.py"
    click RemoteLogin "https://github.com/janeczku/calibre-web/blob/master/cps/remotelogin.py"
    click Basic "https://github.com/janeczku/calibre-web/blob/master/cps/basic.py"
    click Comic "https://github.com/janeczku/calibre-web/blob/master/cps/comic.py"
    click EPUB "https://github.com/janeczku/calibre-web/blob/master/cps/epub.py"
    click MetaProvider "https://github.com/janeczku/calibre-web/tree/master/cps/metadata_provider"
    click Tasks "https://github.com/janeczku/calibre-web/tree/master/cps/tasks"
    click Services "https://github.com/janeczku/calibre-web/tree/master/cps/services"
    click Helper "https://github.com/janeczku/calibre-web/blob/master/cps/helper.py"
    click Logger "https://github.com/janeczku/calibre-web/blob/master/cps/logger.py"
    click CacheBuster "https://github.com/janeczku/calibre-web/blob/master/cps/cache_buster.py"
    click FileHelper "https://github.com/janeczku/calibre-web/blob/master/cps/file_helper.py"

    %% Click Events - Data Persistence
    click CalibreDB "https://github.com/janeczku/calibre-web/blob/master/library/metadata.db"
    click Config "https://github.com/janeczku/calibre-web/blob/master/cps/config_sql.py"

    %% Click Events - External Integrations
    click Converter "https://github.com/janeczku/calibre-web/blob/master/cps/converter.py"
    click Subproc "https://github.com/janeczku/calibre-web/blob/master/cps/subproc_wrapper.py"
    click GDrive "https://github.com/janeczku/calibre-web/blob/master/cps/gdrive.py"
    click GDriveUtils "https://github.com/janeczku/calibre-web/blob/master/cps/gdriveutils.py"
    click Kobo "https://github.com/janeczku/calibre-web/tree/master/cps/kobo"
    click KoboAuth "https://github.com/janeczku/calibre-web/blob/master/cps/kobo_auth.py"
    click KoboSync "https://github.com/janeczku/calibre-web/blob/master/cps/kobo_sync_status.py"
    click OAuth "https://github.com/janeczku/calibre-web/blob/master/cps/oauth.py"
    click OAuthBB "https://github.com/janeczku/calibre-web/blob/master/cps/oauth_bb.py"
```
