How it works
One catalog server sits in the middle. The portal, e-reader apps, the Calibre plugin, AI agents and the digitalizer reach it over HTTP. It keeps its records in PostgreSQL and hands slow work, such as encryption, OCR and extraction, to workers through a Redis queue.
You will see two names. ELVIRA is the library as a whole. EvilFlowers is the name of its catalog server, which started as a side project before ELVIRA existed, and of the GitHub organization that holds all the code. The architecture docs cover the interfaces in detail.
Components
One publication, step by step
It arrives
A librarian uploads a PDF or EPUB in the portal, a script posts it to the REST API, the Calibre plugin syncs it from a Calibre library, or a published Dataverse dataset is imported. Printed books go through the digitalizer first: scans in, a searchable PDF, a PDF/A master and an EPUB out.
EvilFlowersCatalogcalibre-evilflowersevilflowers-books-digitalizerevilflowers-protocol-python
The catalog files it
The publication gets a record with authors, categories, language and files, in a catalog with its own permissions. One install can host a whole university’s catalogs side by side. Records live in PostgreSQL; files on disk or in S3.
Scans get a text layer
A PDF made of page images has no text to search. The OCR service adds an invisible text layer as a new file and keeps the original. Pages that already have text are skipped.
Workers take it apart
The analyzer finds the page layout, the text service splits paragraphs into sentences and embeds them, the image service crops figures and the equation service turns formulas into LaTeX. Each worker posts its results back to the catalog. Titles lent with Readium LCP are never read by AI.
evilflowers-analyzer-serviceevilflowers-text-serviceevilflowers-image-serviceevilflowers-equation-service
It becomes searchable
Search runs inside the catalog’s PostgreSQL: full-text search with Slovak and Czech stemming, ranked by meaning as well as words, down to the paragraph. The assistant answers questions from the same passages and links to the pages it used.
It can be lent
If a title is lent with DRM, the lcpencrypt worker encrypts it and registers it with the Readium LCP server. Readers borrow, renew and return it in the portal or in any LCP-capable app such as Thorium, and join a waiting list when all copies are out.
Someone reads it
Most readers open it in the portal’s reader, where they can search the text, highlight and cite. Others add the catalog’s OPDS feed to their e-reader app. AI agents search and curate the catalog through its MCP server.
Repositories
Everything is public under github.com/EvilFlowersCatalog.
Core
What you deploy to run a library: the catalog server, the portal readers sign in to, and the PDF reader inside it.
| Repository | What it does |
|---|---|
| EvilFlowersCatalogPython | EvilFlowersCatalog is the server every other component talks to. This Django application stores publications, users and loans, serves them over OPDS 1.2, OPDS 2.0 and a REST API, and can host many separate catalogs in one install.DocumentationReleases |
| elvira-portalTypeScript | Readers and librarians use the portal to search the catalog, borrow LCP titles, manage loans and reservations, keep a shelf and read PDFs in the built-in reader. It is a React and Vite app in Slovak and English, themed per institution at build time. |
| EvilFlowersViewerVue | EvilFlowersViewer is the PDF reader inside the portal. It is built on pdf.js, published on npm, and supports search inside the document, highlights and notes, page-range sharing and citation export. Asking the assistant about a selection or a figure is in beta.DocumentationReleases |
Ingest and sync
Ways to get books in and out besides the portal.
| Repository | What it does |
|---|---|
| evilflowers-books-digitalizerPython | The digitalizer takes TIFF scans of printed books, cleans the pages and runs Slovak OCR. For each book it produces a fast distribution PDF, a PDF/A-2b archival master and an EPUB, then publishes the book to the catalog. It runs as a batch job or as a web studio for reviewing books page by page.Documentation |
| calibre-evilflowersPython | A Calibre plugin that keeps a Calibre library in sync with a catalog: books, metadata, covers and EPUB, PDF and MOBI files, in both directions. Point several computers at one catalog and they share a library. It also browses the catalog, manages your shelf and reads back your highlights from the reader.DocumentationReleases |
Lending
Readium LCP lending. The worker encrypts files; the LCP server issues licenses. Readers only ever talk to the catalog.
| Repository | What it does |
|---|---|
| evilflowers-lcpencrypt-workerPython | This Celery worker encrypts each file the catalog marks for lending with Readium’s lcpencrypt, registers it with the LCP server and reports the result back to the catalog. |
| readium-lcp-serverGo | This repository packages the upstream Readium LCP server for our deployments. The server issues licenses and the License Status Documents reading apps use to renew and return loans. Only the catalog talks to it. |
Processing
Workers that process files after upload: OCR for scanned PDFs, and extraction of paragraphs, figures, tables and formulas.
| Repository | What it does |
|---|---|
| evilflowers-ocr-servicePython | The OCR service adds an invisible text layer to scanned PDFs so they can be searched and extracted. It writes a new file and never touches the original, skips pages that already have text, and uses Tesseract by default with RapidOCR as an option. |
| evilflowers-analyzer-servicePython | The analyzer starts each extraction run. It opens the PDF, finds the page layout with Docling, and sends paragraphs and tables to the text service, figures to the image service and formulas to the equation service. |
| evilflowers-text-servicePython | The text service extracts paragraphs and their sentences with positions on the page, and embeds each paragraph so similar passages can be found. It also converts tables to Markdown and embeds the queries for passage search. |
| evilflowers-image-servicePython | The image service crops each figure out of the page so readers can browse a publication’s figures. Generated captions are optional and off by default. |
| evilflowers-equation-servicePython | The equation service crops each formula and reads it back as LaTeX with a LaTeX-OCR model, so equations can be searched and copied. |
Protocol and data
The API contract and its Python client, the shared worker runtime and CI actions, and the PostgreSQL image the catalog runs on.
| Repository | What it does |
|---|---|
| evilflowers-protocolOpenAPI | This repository holds the OpenAPI definition of the catalog API, generated from the catalog source for each catalog branch. |
| evilflowers-protocol-pythonPython | This typed Python client is generated from the protocol. The digitalizer publishes books with it, and you can use it for your own scripts and imports. |
| evilflowers-postgresqlDocker | This is the PostgreSQL 18 image the catalog runs on, with pgvector for embeddings, pg_search for BM25 ranking, and pg_cron and pgaudit for operations.Releases |
| evilflowers-workerPython | The shared runtime of the Celery workers: the message contract with the catalog, the catalog client, delivery and shutdown rules, and telemetry. A new worker is a few small files on top of it. |
| evilflowers-actionsGitHub Actions | Shared GitHub Actions for the services: build the container image, tag it for the branch or release, and deploy it. A service that uses them publishes the image :X.Y.Z for a release tag X.Y.Z. New this month; the services are moving to it. |
Student team projects
FIIT STU students work on ELVIRA in yearly team projects and theses. These are the repositories they left.
- TP2025-T23 Website of FIIT STU team 23, academic year 2025/26.
- evilflowers-text-service-tp2025 The 2025/26 team’s fork of the text service.
- elvira-ai-agent A student prototype of a chat assistant for the portal. The assistant is now part of the catalog.
- TP2024-T5 Website of FIIT STU team 5, academic year 2024/25.
- TP2022-T16 Website of FIIT STU team 16, academic year 2022/23, an early team project on ELVIRA.
Earlier experiments
Nobody works on these and nothing in production depends on them.
- evilflowers-importer A command-line importer that used an LLM to extract metadata into JSON for the catalog.
- evilflowers-ocr-worker A Celery worker around ocrmypdf. Replaced by evilflowers-ocr-service, which keeps the original file.
- evilflowers-search-service A separate keyword and vector index for search. Archived: since catalog 0.15.0, search runs in the catalog’s own PostgreSQL.
- evilflowers-video-service A Whisper transcription prototype for video publications.
- notion-opds An OPDS feed served from a Notion database.
- EvilFlowersFE The first admin frontend for the catalog, in Angular.
Standards
- OPDS 1.2 Atom catalog feeds, read by most e-reader apps.
- OPDS 2.0 JSON catalog feeds with search, pagination and borrowing.
- Readium LCP Open DRM for lending e-books and PDFs.
- Readium LSD License Status Document: renew, return and revoke loans.
- Readium Web Pub Manifest JSON manifest for publications in OPDS 2.0 feeds.
- Model Context Protocol Lets AI agents search and curate the catalog as tools.