How janeczku/calibre-web works
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.