# hectordoesgorug/bookledger architecture

> Architecture diagram of the GitHub repository hectordoesgorug/bookledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hectordoesgorug/bookledger
- Repository: https://github.com/hectordoesgorug/bookledger

## Overview

BookLedger is an offline-first desktop inventory manager with an Android capture companion. The principal workflow is desktop cataloging: users enter a book manually or look up metadata, then manage bibliographic records and physical copies, including photos, condition, location, price, and status. The phone can send ISBN or no-ISBN captures and cover photos to the desktop over a local network for cataloging. Reports, sales history, posters, currency conversion, backups, and updates are distinct product capabilities. Some service links are documented only by README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`src/bookledger/app.py`](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/app.py) (Desktop app), [`src/bookledger/services/mobile_connection.py`](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/mobile_connection.py) (Desktop mobile connection), [`src/bookledger/services/catalog.py`](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/catalog.py) (Books and copies), [`src/bookledger/services/metadata.py`](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/metadata.py) (Metadata lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop catalog"]
  node_desktop_app["Desktop app<br/>[app.py]"]
  node_catalog_ui["Catalog forms<br/>[forms.py]"]
end

subgraph group_services["Domain services"]
  node_catalog["Books and copies<br/>[catalog.py]"]
  node_database[("Library database<br/>[database.py]")]
  node_photos["Copy photos<br/>[photos.py]"]
  node_metadata["Metadata lookup<br/>[metadata.py]"]
  node_provider_registry["Provider registry"]
  node_providers["Metadata providers"]
  node_currency["Currency conversion<br/>[currency.py]"]
  node_sales["Sales history<br/>[catalog.py]"]
  node_reports["Reports<br/>[reports.py]"]
  node_posters["Copy posters<br/>[posters.py]"]
end

subgraph group_mobile["Mobile companion"]
  node_mobile_app["Android companion<br/>[MainActivity.kt]"]
  node_mobile_connection["Desktop mobile connection"]
  node_mobile_incoming["Incoming captures<br/>[mobile_incoming.py]"]
  node_mobile_setup["Pairing setup"]
end

subgraph group_maintenance["Library maintenance"]
  node_backups["Backup and restore<br/>[backups.py]"]
  node_updates["Update flow<br/>[updates.py]"]
  node_config["App configuration<br/>[config.py]"]
  node_provider_settings["Provider settings"]
end

node_user(("BookLedger user"))
node_phone(("Phone user"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"opens forms"| node_catalog_ui
node_catalog_ui -->|"requests lookup"| node_metadata
node_desktop_app -->|"manages inventory"| node_catalog
node_catalog -->|"reads and writes"| node_database
node_catalog -->|"imports photos"| node_photos
node_desktop_app -->|"uses lookup"| node_metadata
node_metadata -->|"builds providers"| node_provider_registry
node_provider_registry -->|"registers providers"| node_providers
node_desktop_app -.->|"converts currency"| node_currency
node_desktop_app -->|"manages sales"| node_sales
node_desktop_app -->|"generates reports"| node_reports
node_desktop_app -->|"creates posters"| node_posters
node_desktop_app -->|"backs up library"| node_backups
node_desktop_app -->|"checks updates"| node_updates
node_desktop_app -->|"loads settings"| node_config
node_desktop_app -->|"configures providers"| node_provider_settings
node_phone -->|"captures books"| node_mobile_app
node_mobile_app -->|"sends captures"| node_mobile_connection
node_mobile_setup -->|"pairs devices"| node_mobile_connection
node_mobile_connection -->|"dispatches captures"| node_mobile_incoming
node_mobile_connection -->|"transfers captures"| node_desktop_app

click node_desktop_app "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/app.py"
click node_catalog_ui "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/ui/forms.py"
click node_catalog "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/catalog.py"
click node_database "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/db/database.py"
click node_photos "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/photos.py"
click node_metadata "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/metadata.py"
click node_provider_registry "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/provider_registry.py"
click node_providers "https://github.com/hectordoesgorug/bookledger/tree/main/src/bookledger/services"
click node_currency "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/currency.py"
click node_sales "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/catalog.py"
click node_reports "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/reports.py"
click node_posters "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/posters.py"
click node_mobile_app "https://github.com/hectordoesgorug/bookledger/blob/main/mobile/android/app/src/main/kotlin/com/bookledger/mobile/MainActivity.kt"
click node_mobile_connection "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/mobile_connection.py"
click node_mobile_incoming "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/mobile_incoming.py"
click node_mobile_setup "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/ui/mobile_app_setup.py"
click node_backups "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/backups.py"
click node_updates "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/updates.py"
click node_config "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/config.py"
click node_provider_settings "https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/provider_settings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_app,node_catalog_ui,node_user,node_phone toneBlue
class node_catalog,node_database,node_photos,node_metadata,node_provider_registry,node_providers,node_currency,node_sales,node_reports,node_posters toneAmber
class node_mobile_app,node_mobile_connection,node_mobile_incoming,node_mobile_setup toneMint
class node_backups,node_updates,node_config,node_provider_settings toneRose
```

## Components

### Desktop catalog

- [Desktop app](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/app.py): `src/bookledger/app.py`
- [Catalog forms](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/ui/forms.py): `src/bookledger/ui/forms.py`

### Domain services

- [Books and copies](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/catalog.py): `src/bookledger/services/catalog.py`
- [Library database](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/db/database.py): `src/bookledger/db/database.py`
- [Copy photos](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/photos.py): `src/bookledger/services/photos.py`
- [Metadata lookup](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/metadata.py): `src/bookledger/services/metadata.py`
- [Provider registry](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/provider_registry.py): `src/bookledger/provider_registry.py`
- [Metadata providers](https://github.com/hectordoesgorug/bookledger/tree/main/src/bookledger/services): `src/bookledger/services`
- [Currency conversion](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/currency.py): `src/bookledger/services/currency.py`
- [Sales history](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/catalog.py): `src/bookledger/services/catalog.py`
- [Reports](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/reports.py): `src/bookledger/services/reports.py`
- [Copy posters](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/posters.py): `src/bookledger/services/posters.py`

### Mobile companion

- [Android companion](https://github.com/hectordoesgorug/bookledger/blob/main/mobile/android/app/src/main/kotlin/com/bookledger/mobile/MainActivity.kt): `mobile/android/app/src/main/kotlin/com/bookledger/mobile/MainActivity.kt`
- [Desktop mobile connection](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/mobile_connection.py): `src/bookledger/services/mobile_connection.py`
- [Incoming captures](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/mobile_incoming.py): `src/bookledger/services/mobile_incoming.py`
- [Pairing setup](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/ui/mobile_app_setup.py): `src/bookledger/ui/mobile_app_setup.py`

### Library maintenance

- [Backup and restore](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/backups.py): `src/bookledger/services/backups.py`
- [Update flow](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/services/updates.py): `src/bookledger/services/updates.py`
- [App configuration](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/config.py): `src/bookledger/config.py`
- [Provider settings](https://github.com/hectordoesgorug/bookledger/blob/main/src/bookledger/provider_settings.py): `src/bookledger/provider_settings.py`

### Other components

- **BookLedger user**
- **Phone user**

## Connections

- BookLedger user → Desktop app: uses (evidence: `README.md`)
- Desktop app → Catalog forms: opens forms (evidence: `src/bookledger/app.py`)
- Catalog forms → Metadata lookup: requests lookup (evidence: `src/bookledger/ui/forms.py`)
- Desktop app → Books and copies: manages inventory (evidence: `src/bookledger/app.py`)
- Books and copies → Library database: reads and writes (evidence: `src/bookledger/services/catalog.py`)
- Books and copies → Copy photos: imports photos (evidence: `src/bookledger/services/catalog.py`)
- Desktop app → Metadata lookup: uses lookup (evidence: `src/bookledger/app.py`)
- Metadata lookup → Provider registry: builds providers (evidence: `src/bookledger/services/metadata.py`)
- Provider registry → Metadata providers: registers providers (evidence: `src/bookledger/provider_registry.py`)
- Desktop app → Currency conversion: converts currency (evidence: `README.md`)
- Desktop app → Sales history: manages sales (evidence: `README.md`)
- Desktop app → Reports: generates reports (evidence: `src/bookledger/app.py`)
- Desktop app → Copy posters: creates posters (evidence: `src/bookledger/app.py`)
- Desktop app → Backup and restore: backs up library (evidence: `src/bookledger/app.py`)
- Desktop app → Update flow: checks updates (evidence: `src/bookledger/app.py`)
- Desktop app → App configuration: loads settings (evidence: `src/bookledger/app.py`)
- Desktop app → Provider settings: configures providers (evidence: `src/bookledger/app.py`)
- Phone user → Android companion: captures books (evidence: `README.md`)
- Android companion → Desktop mobile connection: sends captures (evidence: `README.md`)
- Pairing setup → Desktop mobile connection: pairs devices (evidence: `src/bookledger/ui/mobile_app_setup.py`)
- Desktop mobile connection → Incoming captures: dispatches captures (evidence: `src/bookledger/services/mobile_connection.py`)
- Desktop mobile connection → Desktop app: transfers captures (evidence: `README.md`)
