Bibliotheca/docs

Bibliotheca Architecture Overview

This document links together the module overviews and describes how a book flows through the system.

High-level flow

1. Import (BookImport, Sha256)
   • Compute SHA-256 id for each selected file.
   • Extract metadata and cover (EPUB via libzip/tinyxml2, PDF via poppler).
   • Detect duplicate imports via hash matching.
2. Persistence (DatabaseManager)
   • Ensure the SQLite schema exists (books, tags, book_tags tables).
   • Insert/update/remove records using prepared statements.
   • Manage book-tag associations.
3. Model (BookList)
   • Load books from the database into memory.
   • Expose CRUD helpers with signal emission.
   • Provide thread-safe enqueue helpers for background imports.
4. Presentation (BookShelf, BookTile, BookDetails)
   • Mirror the model into a Gio::ListStore.
   • Render a grid of tiles, expose activation, and filter results.
   • Show detailed view with metadata and tag management.
5. Application shell (BibliothecaWindow)
   • Build the UI chrome (header, search bar, stack pages, toast overlay).
   • React to imports, search queries, and user activation.
   • Handle keyboard navigation and user feedback via toasts.

Module documentation

• BookImport
• DatabaseManager
• BookList
• BookShelf
• BookTile
• BookDetails
• BibliothecaWindow
• SHA-256 helper
• Entry point

External dependencies

• GTK 4 / gtkmm: UI toolkit for widgets, signals, and layout.
• SQLite3: persistence layer for book metadata.
• poppler-glib: PDF metadata/covers.
• libzip + tinyxml2: EPUB metadata extraction.
• OpenSSL (libcrypto): SHA-256 hashing.

Implemented features

• Batch operations: Multi-select mode with rubberband selection, batch tagging, batch delete.
• Tag management: Rename, merge, and delete tags via dedicated dialog.
• Settings panel: Adjustable tile size, default import folder, library maintenance.
• File change detection: Scan for and remove books with missing files.
• Accessibility: Descriptive tooltips for all buttons/controls for screen reader support.

Future work

• Add ADRs (docs/decisions/) for larger architectural choices.
• Document additional subsystems as they appear (e.g., reader view).
• Add screenshots or diagrams for quick onboarding.