Skip to content

Latest commit

 

History

History

docs

README.md

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.

⌂ Proxy