# gitbito/openlibrary architecture

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

- Interactive diagram: https://gitdiagram.com/gitbito/openlibrary
- Repository: https://github.com/gitbito/openlibrary

## Overview

Open Library is an editable, web-based book catalog that also exposes catalog APIs, search, online reading, and lending. A typical workflow starts with a reader or cataloger using the web application, which serves catalog and account operations; catalog records are imported or edited, grouped into works and editions, indexed for discovery, and linked to reading and lending services. The graph includes catalog-ingest and search/indexing branches alongside the user workflow. Some major capabilities are documented but their runtime wiring was not sampled, so those relationships are shown only where supported or are omitted.

Main entry points: [`openlibrary/core/lending.py`](https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/lending.py) (Lending service), [`openlibrary/catalog/add_book/__init__.py`](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/add_book/__init__.py) (Catalog editing), [`openlibrary/catalog/works/by_author.py`](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/works/by_author.py) (Work matching), [`openlibrary/app.py`](https://github.com/gitbito/openlibrary/blob/main/openlibrary/app.py) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web application<br/>[app.py]"]
  node_account["Accounts<br/>[model.py]"]
end

subgraph group_catalog["Catalog and ingest"]
  node_catalog_edit["Catalog editing<br/>[__init__.py]"]
  node_record_load["Record loading<br/>[load_book.py]"]
  node_marc_parse["MARC parsing<br/>[fast_parse.py]"]
  node_record_merge["Record merging<br/>[merge.py]"]
  node_work_matching["Work matching<br/>[by_author.py]"]
  node_archive_import["Archive imports<br/>[get_ia.py]"]
end

subgraph group_discovery["Search and data"]
  node_search_ui["Search interface<br/>[solr_client.py]"]
  node_search_service["Search API<br/>[searchapi.py]"]
  node_index_records["Search indexing data<br/>[solr.py]"]
  node_data_exports["Catalog exports<br/>[dump.py]"]
end

subgraph group_reading["Reading and lending"]
  node_lending["Lending service<br/>[lending.py]"]
  node_waiting_list["Waiting list<br/>[waitinglist.py]"]
  node_loan_views["Loan statistics<br/>[loanstats.py]"]
end

subgraph group_platform["Shared services"]
  node_covers["Cover service<br/>[code.py]"]
  node_catalog_db[("Catalog database<br/>[db.py]")]
end

node_reader(("Readers and catalogers"))
node_archive_org["Internet Archive"]
node_solr[("Solr")]

node_reader -->|"uses"| node_webapp
node_webapp -.->|"serves account views"| node_account
node_webapp -.->|"serves catalog edits"| node_catalog_edit
node_catalog_edit -->|"loads records"| node_record_load
node_catalog_edit -->|"merges records"| node_record_merge
node_record_load -.->|"parses MARC"| node_marc_parse
node_work_matching -->|"retrieves archive data"| node_archive_import
node_work_matching -->|"parses fields"| node_marc_parse
node_work_matching -.->|"uses merge logic"| node_record_merge
node_reader -->|"searches catalog"| node_search_ui
node_search_ui -.->|"queries"| node_solr
node_search_service -.->|"queries"| node_solr
node_index_records -.->|"prepares index data"| node_solr
node_data_exports -->|"uses indexing data"| node_index_records
node_reader -->|"borrows books"| node_lending
node_lending -->|"uses account data"| node_account
node_lending -->|"checks availability"| node_archive_org
node_lending -.->|"coordinates queue"| node_waiting_list
node_loan_views -->|"reads loan data"| node_lending
node_reader -.->|"views covers"| node_covers
node_catalog_edit -.->|"updates records"| node_catalog_db
node_account -.->|"stores accounts"| node_catalog_db
node_covers -->|"uses database"| node_catalog_db

click node_webapp "https://github.com/gitbito/openlibrary/blob/main/openlibrary/app.py"
click node_account "https://github.com/gitbito/openlibrary/blob/main/openlibrary/accounts/model.py"
click node_catalog_edit "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/add_book/__init__.py"
click node_record_load "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/add_book/load_book.py"
click node_marc_parse "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/marc/fast_parse.py"
click node_record_merge "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/merge/merge.py"
click node_work_matching "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/works/by_author.py"
click node_archive_import "https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/get_ia.py"
click node_search_ui "https://github.com/gitbito/openlibrary/blob/main/openlibrary/plugins/search/solr_client.py"
click node_search_service "https://github.com/gitbito/openlibrary/blob/main/openlibrary/plugins/worksearch/searchapi.py"
click node_index_records "https://github.com/gitbito/openlibrary/blob/main/openlibrary/data/solr.py"
click node_data_exports "https://github.com/gitbito/openlibrary/blob/main/openlibrary/data/dump.py"
click node_lending "https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/lending.py"
click node_waiting_list "https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/waitinglist.py"
click node_loan_views "https://github.com/gitbito/openlibrary/blob/main/openlibrary/views/loanstats.py"
click node_covers "https://github.com/gitbito/openlibrary/blob/main/openlibrary/coverstore/code.py"
click node_catalog_db "https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/db.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_webapp,node_account toneBlue
class node_catalog_edit,node_record_load,node_marc_parse,node_record_merge,node_work_matching,node_archive_import,node_solr toneAmber
class node_search_ui,node_search_service,node_index_records,node_data_exports toneMint
class node_lending,node_waiting_list,node_loan_views toneRose
class node_covers,node_catalog_db,node_reader,node_archive_org toneIndigo
```

## Components

### Web application

- [Web application](https://github.com/gitbito/openlibrary/blob/main/openlibrary/app.py): `openlibrary/app.py`
- [Accounts](https://github.com/gitbito/openlibrary/blob/main/openlibrary/accounts/model.py): `openlibrary/accounts/model.py`

### Catalog and ingest

- [Catalog editing](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/add_book/__init__.py): `openlibrary/catalog/add_book/__init__.py`
- [Record loading](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/add_book/load_book.py): `openlibrary/catalog/add_book/load_book.py`
- [MARC parsing](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/marc/fast_parse.py): `openlibrary/catalog/marc/fast_parse.py`
- [Record merging](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/merge/merge.py): `openlibrary/catalog/merge/merge.py`
- [Work matching](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/works/by_author.py): `openlibrary/catalog/works/by_author.py`
- [Archive imports](https://github.com/gitbito/openlibrary/blob/main/openlibrary/catalog/get_ia.py): `openlibrary/catalog/get_ia.py`

### Search and data

- [Search interface](https://github.com/gitbito/openlibrary/blob/main/openlibrary/plugins/search/solr_client.py): `openlibrary/plugins/search/solr_client.py`
- [Search API](https://github.com/gitbito/openlibrary/blob/main/openlibrary/plugins/worksearch/searchapi.py): `openlibrary/plugins/worksearch/searchapi.py`
- [Search indexing data](https://github.com/gitbito/openlibrary/blob/main/openlibrary/data/solr.py): `openlibrary/data/solr.py`
- [Catalog exports](https://github.com/gitbito/openlibrary/blob/main/openlibrary/data/dump.py): `openlibrary/data/dump.py`

### Reading and lending

- [Lending service](https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/lending.py): `openlibrary/core/lending.py`
- [Waiting list](https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/waitinglist.py): `openlibrary/core/waitinglist.py`
- [Loan statistics](https://github.com/gitbito/openlibrary/blob/main/openlibrary/views/loanstats.py): `openlibrary/views/loanstats.py`

### Shared services

- [Cover service](https://github.com/gitbito/openlibrary/blob/main/openlibrary/coverstore/code.py): `openlibrary/coverstore/code.py`
- [Catalog database](https://github.com/gitbito/openlibrary/blob/main/openlibrary/core/db.py): `openlibrary/core/db.py`

### Other components

- **Readers and catalogers**
- **Internet Archive**
- **Solr**

## Connections

- Readers and catalogers → Web application: uses
- Web application → Accounts: serves account views
- Web application → Catalog editing: serves catalog edits
- Catalog editing → Record loading: loads records (evidence: `openlibrary/catalog/add_book/__init__.py`)
- Catalog editing → Record merging: merges records (evidence: `openlibrary/catalog/add_book/__init__.py`)
- Record loading → MARC parsing: parses MARC
- Work matching → Archive imports: retrieves archive data (evidence: `openlibrary/catalog/works/by_author.py`)
- Work matching → MARC parsing: parses fields (evidence: `openlibrary/catalog/works/by_author.py`)
- Work matching → Record merging: uses merge logic
- Readers and catalogers → Search interface: searches catalog
- Search interface → Solr: queries
- Search API → Solr: queries
- Search indexing data → Solr: prepares index data
- Catalog exports → Search indexing data: uses indexing data (evidence: `openlibrary/data/dump.py`)
- Readers and catalogers → Lending service: borrows books
- Lending service → Accounts: uses account data (evidence: `openlibrary/core/lending.py`)
- Lending service → Internet Archive: checks availability (evidence: `openlibrary/core/lending.py`)
- Lending service → Waiting list: coordinates queue
- Loan statistics → Lending service: reads loan data (evidence: `openlibrary/views/loanstats.py`)
- Readers and catalogers → Cover service: views covers
- Catalog editing → Catalog database: updates records
- Accounts → Catalog database: stores accounts
- Cover service → Catalog database: uses database (evidence: `openlibrary/coverstore/code.py`)