This page is the reference for where code lives and how the parts connect.
- Frontend
apps/desktop/src(React + TS) — screens, components, view state. Talks to Rust only via generated IPC clientlib/ipc; reads book bytes viabook://. No FS, SQL or business rules. - Tauri shell
apps/desktop/src-tauri— app setup, AppState, thin#[tauri::command]adapters (one file per feature), typed events,book://protocol, capabilities. - Service crates
crates/libreri-*— all business logic, no Tauri dependency; each owns one feature area and implements core ports. - Core
crates/libreri-core— domain types, IDs, errors, traits (ports), settings schema. Depends only on serde/thiserror.
libreri/
├─ apps/desktop/
│ ├─ src-tauri/ src/{main.rs, state.rs, commands/, events.rs, protocol.rs} capabilities/ tauri.conf.json
│ └─ src/
│ ├─ app/ providers, router, shell layout, error boundary
│ ├─ features/ canvas command-palette details feeds helpers library notes organize
│ │ podcasts portability profiles reader search settings speech spell study
│ │ (each: components/ hooks/ store.ts api.ts index.ts; markup, edit pages,
│ │ compare, capture, weblinks, listening, print and speech live under reader/)
│ ├─ readers/ types.ts (Renderer interface) + pdf/ ebook/ document/ (Markdown, text, RTF)
│ │ pages/ (comics, DjVu) markup/ math/ speech/ focus.ts (ADHD reading)
│ ├─ components/ ui/ (shadcn, generated) · common/ (BookCover, TagChip, Kbd…)
│ ├─ lib/ ipc/ (tauri-specta bindings) · shortcuts/ · tabs/ · floating/ (the folding
│ │ player) · print/ · polyfills.ts (older WebKit) · useWide · useSideOver · utils
│ ├─ styles/ tokens.css, themes, reader themes
│ └─ main.tsx
├─ crates/
│ ├─ libreri-core domain types, IDs, errors, ports
│ ├─ libreri-db SQLite, migrations, repositories, FTS5
│ ├─ libreri-library library folder, lock, scan, watcher, import/move, hashing, sidecars, versions
│ ├─ libreri-formats extractors: pdf, epub, mobi, fb2, txt, md, comics (zip/rar/7z/tar/ace), djvu (pages, text layer, outline), mobi/azw3, audio; text (book text in pieces), pdftext (hayro: PDF text, page images for OCR), ocr (Tesseract TSV)
│ ├─ libreri-thumbs thumbnails, covers
│ ├─ libreri-metadata online details: sources (Open Library, Google Books, Crossref, OpenAlex, Semantic Scholar, arXiv, ComicVine, ISBNdb), scoring, tag/category tidying, cover download
│ ├─ libreri-helpers helper programs (DjVuLibre, Tesseract, unar, eSpeak NG): find, version, install with the package manager, run; OCR language data (tessdata); downloads with stall detection; eSpeak speech
│ ├─ libreri-scan barcode reading (rxing) and the one-time phone page for scanning
│ ├─ libreri-feeds RSS/Atom/OPML parsing and fetching, arXiv, suggested sources, Markdown articles, podcasts (Apple and Podcast Index search)
│ ├─ libreri-ocr optional OCR models (PaddleOCR-VL with PP-DocLayout, run with candle): download, remove, load, read regions
│ ├─ libreri-voices natural voices (Kokoro, Piper): downloads, the Piper list and licences, ONNX Runtime loaded at run time, phonemes with eSpeak NG, WAV
│ ├─ libreri-profiles 6-digit PIN rules, Argon2 hashing, lockout, recovery codes
│ ├─ libreri-search full-text index (SQLite FTS5, per computer): pieces, stamps, queries, snippets
│ ├─ libreri-export formats: CSV/XLSX/JSON, BibTeX/RIS/CSL-JSON, citation styles, Obsidian notes, Calibre OPF, Libreri archives (zip + manifest); importers from other apps (4c)
│ ├─ libreri-pdf-edit marked-up copies; page edits, redaction, corrections, OCR text layer, compression, PDF annotations; compare and report
│ ├─ libreri-links links to pages and videos: address reading (YouTube, Vimeo, start times), oEmbed details, offline copies (dom_smoothie + ammonia), the local player page
│ ├─ libreri-maths reading maths from pictures as LaTeX (pix2tex run with candle), model download
│ ├─ libreri-spell spell check (Hunspell dictionaries via spellbook), dictionary downloads, word completion learned from books and notes
│ ├─ libreri-speech speech recognition (whisper.cpp): models, audio decoding (symphonia), FLAC voice notes, transcription, audiobook ↔ text matching
│ └─ libreri-jobs background queue, progress, cancellation
│ (Annotations live in libreri-library; each model
│ has its own crate — libreri-speech, libreri-maths, libreri-ocr, libreri-voices.)
├─ packages/config/ shared tsconfig, eslint, tailwind presets
├─ flatpak/ Flatpak manifest, desktop file and metainfo
├─ assets/ docs/adr/ tests/e2e/ scripts/ .github/workflows/
└─ Cargo.toml pnpm-workspace.yaml rust-toolchain.toml README.md LICENSE (GPL-3.0-or-later)
PRIVACY.md TERMS.md CLA.md CONTRIBUTING.md
- Open book: UI → reader feature →
lib/ipc.openBook→commands/reader.rs→libreri-library::open(bookId, profile)→libreri-db(record + position) →BookHandle→ renderer chosen by format → bytes streamed viabook://file/{token}(range requests) → page at saved position. - Import: drop →
api.importFiles→commands/library.rs::import_files→libreri-jobsqueue → BLAKE3 hash → duplicate check (skip/replace/keep both) → move/copy intoBooks/→libreri-formatsextract →libreri-thumbs→libreri-dbinsert → JSON sidecar → optional online lookup. Progress + books-changed events update the UI. - Page images:
PageRendererasksopen_pagesfor page count, sizes and outline → images load frombook://…/.pages/<bookId>/<page>?w=→libreri-library::pages(CBZ read directly; CBR/CB7/CBT/CBA unpacked once; DjVu rendered byddjvuat width steps) → per-computer page cache. DjVu text comes frompage_words/page_texts(djvutxt). - Search: after each scan the indexer thread (
state.rs) callsLibrary::update_index→libreri-formats::textper changed book (+ saved OCR text) →libreri-search. The search screen callssearch_text/search_in_book; a result opens a tab withfindText, and the reader goes to the page or chapter (prepareFind) and runs Find. Make searchable queues a job:Library::make_searchablerenders pages (hayro / ddjvu), runs Tesseract, saves.library-data/text/<id>.jsonand re-indexes. - Read aloud (with natural voices):
readers/speech/(sentences, maths,DomSpeechfor HTML,WordSpeechfor pages with word boxes;peek()gives the next sentence) behindRenderer.readAloud()→features/reader/speech/(useReadAloudloop;engine.ts: Web Speech, eSpeak NG throughsystem_speak, and natural voices throughspeak_natural, which makes each sentence as a WAV while the one before plays;choose.tspicks the voice for the book's language) → the floating playerfeatures/reader/listening/ListenBar.tsx. - Natural voices: Settings › Reader
sections/ReadAloudVoices.tsxandfeatures/reader/speech/natural.ts→commands/voices.rs(natural_voices,piper_languages,piper_voices,download_voice,remove_voice,set_voice_on,speak_natural) →libreri-voices(runtime.rsONNX Runtime,kokoro.rs,piper.rs,phonemes.rs,fetch.rs,wav.rs). - OCR models: Settings › Helper programs
sections/OcrEngines.tsx→commands/ocr_models.rs→libreri-ocr; Make searchable asksocr_models::readerfor the chosen model throughlibreri-formats::ocr::PageReader. - Podcasts:
features/podcasts/(PodcastsView,FindPodcastsDialog,player.tswith the one<audio>of the window,PodcastPlayerfloating or folded) →commands/feeds.rswith spacepodcasts→libreri-feeds(podcast search and episodes) andFeeds/<profile>/.podcasts.json. - Daily review:
features/review/(model.tscards from highlights, the queue and ts-fsrs scheduling, Anki notes;store.tsthe profile's review document anduseCards;ReviewViewoverview and session;CardOptionsin the highlight menu) →commands/study.rs(review_read,review_write,export_anki) →libreri-library/src/study.rs(<id>.review.json) andlibreri-export/src/anki.rs(.apkg). - Study:
features/study/(CalendarViewwith month, week and day;GoalDialog;TimerButtonin the reader's toolbar;timer.tsthe timer;store.tsthe calendar and where reading is;StudyHostinAppShellticks the timer, shows the break card and mirrors the timer to the menu bar) →commands/study.rs(study_read,study_write,save_calendar_file,timer_traywith Tauri's tray andset_progress_bar) →libreri-library/src/study.rs(.library-data/profiles/<id>.study.json). - Print:
features/reader/print/PrintDialog.tsxdraws PDF pages into a print-only part of the window, thenlib/print→print_window(commands/app.rs). - Audiobooks:
ReaderViewopens audio files infeatures/reader/listening/AudiobookView(<audio>onbook://, chapters fromaudio_info→libreri-formats::audio); links and sync points viaget_audio_link/set_audio_link/set_sync_points→libreri-library/src/listening.rs; theuseListeningstore connects the open audiobook and the open text (follow, add a sync point, listen from here). - Speech:
features/speech/(useRecorder: microphone → 16 kHz PCM,PauseDetectorfor dictation;DictateButton;useVoiceNote+VoiceNoteBar;voice.tsfor links and players in notes) →commands/speech.rs(models,transcribe_pcm,save_voice_note,transcribe_voice_note,auto_sync_audiobookjob) →libreri-speech(whisper, decoding, FLAC,sync) andlibreri-library(voice.rs: recordings in the notes folder;listening.rs:sync_words,add_auto_points). The loaded model is cached inAppState. Settings › Speech isfeatures/settings/components/sections/Speech.tsx. - Writing:
features/spell/(field.ts:attachSpellputs a layer over any<textarea>that draws wavy lines under misspelt words, plus the corrections menu and completion list;useSpell/SpellTextareafor React; markup text boxes throughMarkupEvents.onEditorOpen) →commands/spell.rs(spell_check,spell_suggest,spell_complete, dictionaries, own words) withspell_cache.rs(loaded dictionaries, words of recent books and notes, learned in the background) →libreri-spellandlibreri-library/src/own_words.rs(Notes/<profile>/Dictionary.txt, note texts, book words). Settings › Writing issections/Writing.tsx. - Canvases:
features/canvas/(CanvasPanelin the reader,CanvasEditorwith the paper choice, Clip from page and Ink to text,ExcalidrawHostloaded lazily with saving and the Excalidraw calls,paper.ts) →commands/canvas.rs→libreri-library/src/canvases.rs(files inNotes/<profile>/Canvases/). Clipping isRenderer.clipPicture(readers/clip.ts, PDF and page renderers). Ink to text islibreri-helpers/src/ink.rs(macOS Vision via osascript, Windows OCR via PowerShell) orlibreri-formats::ocr::recognize_block(Tesseract). - Compare:
features/reader/compare/(CompareDialog, CompareView with side-by-side, overlay and change list) →start_compare(commands/compare.rs) →AppState::start_compareopens both sides (Library::compare_doc) and runsLibrary::compareas a job (words frompdftext/djvu, pairing and word diff inlibreri-pdf-edit::compare, looks by rendering) →CompareFinishedevent →get_comparison. Pages come frombook://…/.compare/<id>/<a|b>/<page>;export_compare_report→libreri-pdf-edit::compare_report. - Feeds:
features/feeds/(FeedsViewwith the folder tree, item list and menus;AddFeedDialogwith Address, arXiv, Suggested and OPML tabs;ItemDialogswith the PDF and Markdown preview and Add to library;useFeedsBackgroundinAppShellchecks for new items and listens forFeedsChanged) →commands/feeds.rs(state inFeeds/<profile>/.feeds.jsonunderAppState.feeds_lock;feeds_refreshreads feeds six at a time, then downloads for auto-download feeds;feed_item_download,feed_item_to_library) →libreri-feeds(parsewith feed-rs,fetchwith discovery and downloads,state,opml,sourcesfor arXiv and suggestions,articlefor Markdown) andlibreri-library/src/feeds.rs(the folder,book://access, adding to the library, profile rename and delete). Articles uselibreri-links::copy::readable. - Paper notes:
features/reader/capture/(CaptureDialogwith camera, phone and pictures, the corner editor, clean-up and page order;CaptureViewer;captureOf) →commands/capture.rs(capture_add,capture_add_file,capture_preview,capture_savewith Tesseract) →libreri-scan/src/paper.rs(detect, straighten, clean),libreri-pdf-edit::pictures_pdfandlibreri-library/src/captures.rs(Notes/<profile>/Captures/). Notes are annotations of kindcapture. - Maths:
readers/math/latex.ts(mathmlToLatex,textToLatex),RendererEvents.mathClickfrom the document and ebook renderers, andfeatures/reader/components/MathPopover.tsx. Reading from pictures isfeatures/reader/maths/api.ts→commands/maths.rs→libreri-maths(model.rsthe network,prepare.rsthe picture,tokens.rsthe LaTeX). Settings › Writing › Maths is insections/Writing.tsx. - Links:
features/reader/weblinks/(AddLinkDialog,LinksPanelfor the Links tab withPlayer,LinkCard,CopyViewer,model.tswithlinkOf) →commands/links.rs(link_fetch,link_save,link_file,link_media_url,link_player,link_pop_out,link_open_file) →libreri-linksandlibreri-library/src/links.rs(pictures and offline copies in the notes folder).protocol.rsserves.media/<token>/…for linked files and.htmlcopies with a sandbox policy. Clicks on drawn annotations usereaders/types.ts::highlightAt. - Edit pages:
features/reader/edit/(model with undo,PdfPagesthumbnails and text via PDF.js,PageEditorgrid,PageDetailfor crop/redact/correct, dialogs for inserting, new books, compression and version history) →edit_pages/save_pages_as_book/save_filled_form/save_markup_into_pdf(commands/edit.rs) →Library::edit_pagesetc. (libreri-library/src/edit.rs) →libreri-pdf-edit::apply(redact.rs walks content streams, inspect.rs checks with hayro, edit.rs rebuilds pages) →Library::save_version(versions.rs: keeps the old file, changes the id, moves notes through the page map). Phone photos come from thelibreri-scanphone page in pages mode. - Markup:
readers/markup/(model, SVG rendering,MarkupLayercontroller mounted by the PDF and page renderers on each page, export draw list) +features/reader/markup/(useMarkup, toolbar, panel, dialogs). Marks are saved withsave_annotation(kindmarkup); Export marked-up copy sends the draw list toexport_marked_up→Library::export_marked_up→libreri-pdf-edit. - Look up and series:
features/reader/components/LookupPopover.tsx→commands/reader.rs::look_up→libreri-metadata/src/lookup.rs(Wiktionary definitions, Wikipedia summary).features/library/series.ts(grouping, order, next book) andcomponents/SeriesView.tsx; nav kindseries(with a name: that series inLibraryView). - Opening files from the computer:
bundle.fileAssociationsintauri.conf.json(pluslinux/libreri.desktopwith%F) registers the book types. macOS sendsRunEvent::Opened, Windows and Linux pass paths as arguments (a second copy hands them over throughtauri-plugin-single-instance) →commands/opened.rsqueues them and emitsFilesOpened→features/library/opened.tstakes them withtake_opened_files(Library::book_for_filefinds a book with the same content) and opens it, or asks to add it with the import dialog and opens it whenImportFinishedarrives. - Moving a library: Settings › Library & storage › Move… (
MoveLibraryDialog) →plan_library_move/move_library(commands/library.rs; refused while jobs run) →libreri-library::relocate(plan_move;move_closedrenames on the same disk, otherwise copies with progress (LibraryMoveProgress), keeps file times, checks the copy and sends the old folder to the Trash) → the library reopens from its new place and the recent list is updated.
| Adding… | Put it in | Not in |
|---|---|---|
| Button/dialog/screen | features/<f>/components |
components/ui |
| New file format | libreri-formats + readers/<format> |
reader feature |
| Business rule | owning service crate | Tauri command / React hook |
| Table or query | libreri-db migration + repository |
SQL in other crates |
| Metadata source | libreri-metadata/src/providers/ |
lookup screen |
| Keyboard shortcut | lib/shortcuts registry (action ID) |
component keydown listener |
| Setting | schema in core + features/settings |
localStorage |
| Downloadable model | its own crate (libreri-ocr, libreri-voices, …) with download, remove and load, and a Settings group |
installer |
| Fix for an older web view | lib/polyfills.ts |
the feature that needs it |
- Dependencies point down only (CI: ESLint import boundaries, cargo dependency checks).
- Commands are thin: validate → one service call → map error.
- Rust types exported to TS automatically (tauri-specta); never duplicated by hand.
- TanStack Query for data from Rust; Zustand for view state only.
- Features import each other only via
index.ts. - One
Errorenum per crate (thiserror); typed IPC errors with plain-language messages. - Personal data methods in
libreri-dbtake an explicitProfileId; there is no global current user. The signed-in profile belongs to the openLibrarysession so the interface cannot read someone else's data by passing their id (ADR 0010). - Optional capabilities (OCR, handwriting, dictation, maths) are cargo features; models load at runtime.
- Tests next to code (crate unit tests, Vitest), plus e2e for import/open/highlight/export.
- rustfmt, clippy -D warnings, ESLint + Prettier, Conventional Commits, ADRs in
docs/adr.
- The app interface uses one sans-serif family (Geist, falling back to the system UI font) for every heading, label, button and menu. No italic or serif headings anywhere in the app UI.
- Geist Mono only for technical text: file paths, keyboard keys, ISBNs, LaTeX source, timestamps.
- Heading hierarchy comes from size and weight only (e.g. 20/600 page title, 15/600 section, 13/500 labels), defined once as tokens in
styles/tokens.css. - Serif, italic or handwriting fonts appear only inside content, never as UI:
- book pages (the book's own fonts, or the reader font the user picks in Reader settings);
- maths (italic variables are the normal convention, rendered by KaTeX / the PDF);
- text the user writes with a handwriting-style font in Markup or Canvas;
- generated placeholder covers for books without a cover image.