# textbrowser/biblioteq architecture

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

- Interactive diagram: https://gitdiagram.com/textbrowser/biblioteq
- Repository: https://github.com/textbrowser/biblioteq

## Overview

##### Project Type and Purpose
- BiblioteQ is a full-stack, cross-platform desktop (and Android) library management application written in C++/Qt.
- It provides cataloging, search, borrowing workflows and integrates with PostgreSQL or SQLite databases and external metadata sources (Z39.50/SRU, Open Library, Amazon).

##### File Structure
- Top-level:
- Source/ and UI/ contain C++ classes and Qt Designer forms – this is your application frontend + core logic.
- SQL/ holds schema scripts for SQLite and PostgreSQL – your database layer.
- Scripts/ and Tools/ are build‐time or maintenance utilities.
- Android/ contains Gradle and resource files – the mobile wrapper target.
- Distributions/ packaging definitions for different OSes and architectures.
- Look for biblioteq.pro and various .pro files → Qt build system driving multi-target compilation.
- Source code is organized by feature (e.g., biblioteq_book.*, biblioteq_dvd.*) indicating a modular domain‐driven design.

##### README for Additional Insights
- Confirms use of Qt LTS, Poppler (PDF reader), Z39.50, SRU protocols, CSV import/export, multi-database support, and Android build target.
- Mentions free‐standing (network-less) usage and PostgreSQL row-level security features.

a. Main Components
1. UI Layer
2. Application Core / Business Logic
– C++ classes under Source/ (e.g., item classes, query engines, thread managers)
3. Data Access Layer
– Qt SQL abstraction classes interacting with SQLite or PostgreSQL
4. Database Servers
– Local SQLite embedded file
– Remote PostgreSQL server (optional)
5. External Services
– Z39.50/SRU client module for library network queries
– REST API clients for Open Library and Amazon cover retrieval
6. Platform Abstraction
– Android wrapper (Gradle, JNI/CocoaInitializer for macOS, platform .pro files)
7. Build & Distribution
– Qt build system (.pro files), packaging scripts (Distributions/, Scripts/, Tools/)
8. File System & Static Resources

b. Relationships & Interactions
- UI Layer → calls → Application Core
- Application Core → uses → Data Access Layer
- Data Access Layer ↔ queries ↔ Database (SQLite file or PostgreSQL)
- Application Core → invokes → External Services over network (SRU/Z39.50, HTTP REST)
- Platform Abstraction encloses UI/Core for mobile vs. desktop.
- Build & Distribution packages all components per target architecture.

c. Architectural Patterns & Principles
- Layered architecture (Presentation, Business, Data).
- Modular domain classes per item type (Book, DVD, Magazine).
- Plugin-like extensibility via Qt resource files and translation modules.
- Asynchronous operations (threaded retrieval, Qt signals/slots).
- Configuration-driven packaging for multiple OS/architectures.

d. Key Technologies & Frameworks
- Qt (Widgets, Designer, .qrc resources, translations)
- C++17 (business logic, threading)
- SQLite / PostgreSQL (SQL scripts under SQL/ directory)
- Z39.50 / SRU client library
- REST HTTP client (Qt Network)
- Poppler for PDF reading
- Gradle for Android
- Bash scripts & .pro files for packaging

##### Key Details to Capture
- All database options (SQLite vs. PostgreSQL)
- Multi-platform build outputs (Windows, Linux, macOS, Android)
- Asynchronous communication modules (threads, signals/slots for SRU fetches)
- Packaging scripts and their targets (Distributions/*)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UIForms["UI Forms (.ui)"]:::ui
        UITranslations["Translations (translations.qrc)"]:::ui
        UIIcons["Icons (icons.qrc)"]:::ui
        UIAudio["Audio (audio.qrc)"]:::ui
        UIDocs["Documentation (documentation.qrc)"]:::ui
    end

    %% Application Core
    subgraph "Application Core / Business Logic"
        CoreEntry["biblioteq.h / .cc"]:::core
        Books["biblioteq_book.{h,cc}"]:::core
        DVDs["biblioteq_dvd.{h,cc}"]:::core
        CDs["biblioteq_cd.{h,cc}"]:::core
        Magazines["biblioteq_magazine.{h,cc}"]:::core
        GreyLit["biblioteq_grey_literature.{h,cc}"]:::core
        Videogames["biblioteq_videogame.{h,cc}"]:::core
        Photos["biblioteq_photograph*.{h,cc}"]:::core
        Threading["biblioteq_generic_thread.{h,cc}"]:::core
        ImportExport["biblioteq_import/{.h,cc}"]:::core
        QueryHistory["biblioteq_query_history.{h,cc}"]:::core
        MiscFuncs["biblioteq_misc_functions.{h,cc}"]:::core
        PDFReader["biblioteq_pdfreader.{h,cc}"]:::core
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        SchemaHelpers["SQLite/PostgreSQL Schema Helpers"]:::data
        SQLScripts["SQL Scripts (.sql)"]:::data
        CopyEditors["Copy/Borrower Editors"]:::data
    end

    %% Database Servers
    subgraph "Database"
        SQLiteDB(("SQLite File")):::db
        PostgresDB(("PostgreSQL Server")):::db
    end

    %% External Services
    subgraph "External Services"
        Z3950["Z39.50 Client"]:::ext
        SRU["SRU Client"]:::ext
        OpenLibrary["Open Library REST"]:::ext
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction"
        AndroidWrapper["Android Wrapper (Gradle)"]:::plat
        CocoaInit["CocoaInitializer.{h,mm}"]:::plat
        WindowsTarget["biblioteq.windows.pro"]:::plat
    end

    %% Build & Distribution
    subgraph "Build & Distribution"
        QtBuild["Qt Build Files (.pro)"]:::build
        Scripts["Scripts/"]:::build
        Tools["Tools/"]:::build
        DistDefs["Distributions/"]:::build
    end

    %% Static Resources
    subgraph "Static Resources"
        IconsStatic["Icons/"]:::res
        AudioStatic["Audio/"]:::res
        TranslationsStatic["Translations/"]:::res
    end

    %% Relationships
    UIForms -->|"signals/slots"| CoreEntry
    UITranslations -->|resources| CoreEntry
    UIIcons -->|resources| CoreEntry
    UIAudio -->|resources| CoreEntry
    UIDocs -->|resources| CoreEntry

    CoreEntry -->|"uses"| SchemaHelpers
    CoreEntry -->|"calls"| CopyEditors
    CoreEntry -->|"imports/exports"| ImportExport

    SchemaHelpers -->|executes| SQLScripts
    SchemaHelpers -->|drives| SQLiteDB
    SchemaHelpers -->|drives| PostgresDB
    CopyEditors -->|queries| SQLiteDB
    CopyEditors -->|queries| PostgresDB

    CoreEntry -->|"threaded fetch"| Z3950
    CoreEntry -->|"threaded fetch"| SRU
    CoreEntry -->|"HTTP/REST"| OpenLibrary
    PDFReader -->|PDF read| CoreEntry

    QtBuild -->|compiles| AndroidWrapper
    QtBuild -->|compiles| CocoaInit
    QtBuild -->|compiles| WindowsTarget

    Scripts -->|packaging scripts| DistDefs
    Tools -->|versioning| DistDefs
    QtBuild -->|build definitions| DistDefs

    IconsStatic -->|UI assets| UIIcons
    AudioStatic -->|UI assets| UIAudio
    TranslationsStatic -->|UI assets| UITranslations

    %% Click Events
    click UIForms "https://github.com/textbrowser/biblioteq/tree/master/UI/"
    click UITranslations "https://github.com/textbrowser/biblioteq/blob/master/Translations/translations.qrc"
    click UIIcons "https://github.com/textbrowser/biblioteq/blob/master/Icons/icons.qrc"
    click UIAudio "https://github.com/textbrowser/biblioteq/blob/master/Audio/audio.qrc"
    click UIDocs "https://github.com/textbrowser/biblioteq/blob/master/Documentation/documentation.qrc"

    click CoreEntry "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq.h"
    click Books "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_book.cc"
    click DVDs "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_dvd.cc"
    click CDs "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_cd.cc"
    click Magazines "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_magazine.cc"
    click GreyLit "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_grey_literature.cc"
    click Videogames "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_videogame.cc"
    click Photos "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_photographcollection.cc"
    click Threading "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_generic_thread.cc"
    click ImportExport "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_import.cc"
    click QueryHistory "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_query_history.cc"
    click MiscFuncs "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_misc_functions.cc"
    click PDFReader "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_pdfreader.cc"

    click SchemaHelpers "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_sqlite_create_schema.h"
    click SQLScripts "https://github.com/textbrowser/biblioteq/blob/master/SQL/postgresql-create-schema.sql"
    click CopyEditors "https://github.com/textbrowser/biblioteq/blob/master/Source/biblioteq_copy_editor.cc"

    click AndroidWrapper "https://github.com/textbrowser/biblioteq/tree/master/Android/"
    click CocoaInit "https://github.com/textbrowser/biblioteq/blob/master/Source/CocoaInitializer.h"
    click WindowsTarget "https://github.com/textbrowser/biblioteq/blob/master/biblioteq.windows.pro"

    click QtBuild "https://github.com/textbrowser/biblioteq/blob/master/biblioteq.pro"
    click Scripts "https://github.com/textbrowser/biblioteq/tree/master/Scripts/"
    click Tools "https://github.com/textbrowser/biblioteq/tree/master/Tools/"
    click DistDefs "https://github.com/textbrowser/biblioteq/tree/master/Distributions/"

    click IconsStatic "https://github.com/textbrowser/biblioteq/tree/master/Icons/"
    click AudioStatic "https://github.com/textbrowser/biblioteq/tree/master/Audio/"
    click TranslationsStatic "https://github.com/textbrowser/biblioteq/tree/master/Translations/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404;
    classDef db fill:#ffeeba,stroke:#856404,color:#856404,shape:cylinder;
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef plat fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef build fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef res fill:#f5f5f5,stroke:#343a40,color:#343a40;
```
