Architecture
Resolver architecture
How LibreLeaf clusters catalogue records into canonical works, retains editions and offers, and explains cross-source ranking.
Work model
LibreLeaf resolves a work across catalogues instead of treating each search hit as a separate book. A canonical work contains sourceRecords; each source record contains the offers supplied by that catalogue. This preserves the difference between a work, a publication or recording, and an access route.
Stable llw1.* IDs are derived from normalized title and primary author. When usable author metadata is absent, source identity remains part of the key. IDs are shared by saved items, browser permalinks, the public API and MCP fetch.
Clustering
- A shared Open Library work key or identifier can support an exact cluster.
- An exact normalized title and primary-author match can merge records while keeping every source record.
- Title-only or fuzzy similarity does not silently merge translations, abridgements or adaptations.
- Prefer visible duplicates over a false canonical merge when evidence is incomplete.
Ranking
Every source record retains its catalogue position. LibreLeaf combines those positions with Reciprocal Rank Fusion using k=60, then applies a small disclosed exact-title or exact-author signal. A result can therefore benefit from independent source agreement without one catalogue's score dominating the others.
The response exposes the fusion method, contributing ranks and plain-English why values. Ranking never treats affiliate revenue, a file format or a hidden model score as relevance evidence.
rrfScore = Σ 1 / (60 + sourceRank)Availability and editions
Search returns source-provided routes that passed protocol and host allowlists. It does not proxy book files. Open Library editions are loaded only when requested because edition fan-out would slow every search and can confuse work-level relevance.
A current offer can still change after it is indexed. Availability links, source timestamps and rights notes should stay visible. Clients must not substitute one translation or edition merely because its title is similar.