# 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](bookimport.md)
- [DatabaseManager](database_manager.md)
- [BookList](booklist.md)
- [BookShelf](bookshelf.md)
- [BookTile](booktile.md)
- [BookDetails](bookdetails.md)
- [BibliothecaWindow](bibliotheca_window.md)
- [SHA-256 helper](sha256.md)
- [Entry point](main.md)

## 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.