Open Library Knowledge Base

Open Library's in-repo AI knowledge base: how each subsystem actually behaves, verified against the source. Obsidian-style markdown with [[wikilinks]]. It is committed with the repo and reads on its own — no extra tooling required.

This KB consolidates what used to live in two places — the in-repo docs/ai/ guides and the external mekarpeles/openlibrary-kb repo — into one in-repo source of truth under docs/.

Start here:

• ai-coding-guide.md — the canonical AI-agent engineering reference (setup, build, testing, architecture, code style, key file locations). The root bridge files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) point here.
• CONTRIBUTING.md — conventions for adding or editing a KB page.

Sections

Directory	What's in it
core/	Infogami, FastAPI, the database, internal APIs, auth, OTP service
imports/	How records enter the catalog — BookWorm, feed registry, the import contract, add-book internals, MARC encoding, validation
cover-service/	Coverstore and cover archival
search/	Solr indexing, query parsing, text analysis, schema priorities
tags/	The Tags data/vocabulary system (genres, subgenres, audiences), dev setup, known issues
librarians/	The Librarians System — editing UI, merge tools, micro-edits
lending/	Lending & trusted book providers, including Lenny
i18n/	Translation pipeline and rendering
opds/	OPDS feeds
frontend/	Web components, CSS, design, accessibility, BookReader, Library Explorer
client-and-bots/	openlibrary-client and bots
analytics/	Analytics, client-side events, Core Vitals
public-apis/	Public APIs and partials
features/	Reading log, ratings, activity feed, lists, follows

Rules

• One note per file, named in kebab-case; link related notes with [[note-name]], and link liberally.
• One topic = one directory, each with a README.md overview. Keep overviews high-level; deep dives live as named sub-documents linked from the README.md.
• Keep each note to one idea; put the specifics in the note, not in this index.
• In-flight effort/issue progress does not live here — it lives in the corresponding GitHub epic. These pages describe how systems work, not the status of the work on them.
• This KB is the project's durable knowledge: decisions, how-tos, gotchas, references.

This index is only as good as its last update — when you add a page, add it to its directory's README.md in the same commit.