Skip to main content

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

ELVIRA component diagramThe web portal, OPDS reading apps, the Calibre plugin, AI agents and the books digitalizer all talk to EvilFlowersCatalog through its HTTP interfaces. The catalog stores data in PostgreSQL, sends encryption tasks to the lcpencrypt worker and OCR and extraction tasks to the processing workers through Redis, and proxies the Readium LCP server. Extraction workers post their results back to the catalog.elvira-portal: 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.elvira-portalReact web appEvilFlowersViewer: 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.EvilFlowersViewerPDF reader, npmReading appsThorium, any OPDS appCalibre plugin: 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.Calibre plugintwo-way library syncAI agentsany MCP clientbooks-digitalizer: 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.books-digitalizerscans → PDF/A, EPUBREST, files, chatloanscatalog feedsloan statussync, API keytools, API keypublish, API keyEvilFlowersCatalog: 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.EvilFlowersCatalogDjango + Celery. Catalogs, publications, users, loans, annotations.One install hosts many separate libraries./api/v1 · /data/v1 · /assistant/v1/readium/v1/opds/v1.2 · /opds/v2/api/v1/mcp/v1/api/v1/extraction/v1lcpencrypt-worker: 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.lcpencrypt-workerencrypts filesreadium-lcp-server: 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.readium-lcp-serverlicenses, statusregisters encrypted filesPostgreSQL 18: 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.PostgreSQL 18pgvector, pg_searchRedistask queueFileslocal disk or any S3 storeanalyzer: 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.analyzerpage layouttext: 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.textparagraphsimage: 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.imagefiguresequation: The equation service crops each formula and reads it back as LaTeX with a LaTeX-OCR model, so equations can be searched and copied.equationLaTeXocr-service: 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.ocr-servicetext layer for scansencryption tasklicenses, statusSQLCelery tasksextraction taskresultsOCR taskIn the reader’s browserLending · Readium LCPStorageProcessing
Dashed: not part of the projectClick a box to open its repository.

One publication, step by step

  1. 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

  2. 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.

    EvilFlowersCatalogevilflowers-postgresql

  3. 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.

    evilflowers-ocr-service

  4. 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

  5. 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.

    EvilFlowersCatalogevilflowers-postgresql

  6. 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.

    evilflowers-lcpencrypt-workerreadium-lcp-server

  7. 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.

    elvira-portalEvilFlowersViewerEvilFlowersCatalog

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.

RepositoryWhat it does
EvilFlowersCatalogPythonEvilFlowersCatalog 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-portalTypeScriptReaders 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.
EvilFlowersViewerVueEvilFlowersViewer 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.

RepositoryWhat it does
evilflowers-books-digitalizerPythonThe 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-evilflowersPythonA 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.

RepositoryWhat it does
evilflowers-lcpencrypt-workerPythonThis 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-serverGoThis 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.

RepositoryWhat it does
evilflowers-ocr-servicePythonThe 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-servicePythonThe 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-servicePythonThe 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-servicePythonThe 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-servicePythonThe 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.

RepositoryWhat it does
evilflowers-protocolOpenAPIThis repository holds the OpenAPI definition of the catalog API, generated from the catalog source for each catalog branch.
evilflowers-protocol-pythonPythonThis 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-postgresqlDockerThis 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-workerPythonThe 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 ActionsShared 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