>_EXECUTIVE SUMMARY
This report describes zcite-core, the embeddable reference-manager engine inside the zcite app — a pure-Rust crate (crates/zcite-core) that drives the whole library behind one JSON command surface (Engine::invoke(cmd, args), ~155 commands). The pure core compiles with zero TLS or socket dependencies; networked metadata lookup (net) and PDF text extraction (pdf) are default-on Cargo features, and a Tauri v2 host layer is gated behind tauri. The crate builds three artifacts — rlib for native Tauri hosts, plus staticlib/cdylib with a C ABI (include/zcite_core.h) for non-Rust hosts.
~MODULE MAP
Nineteen source modules make up the engine, each with a single responsibility — from the Engine dispatcher and persisted data model through citation formatting, import/export, identifier lookup and the FFI/Tauri host layers.
| Module | Responsibility |
|---|---|
| lib.rs | The Engine and its invoke dispatcher — the single JSON command surface (~155 commands) over the whole library. |
| model.rs | The persisted library data model: typed Items, the Collection tree, colored tags, related items and saved searches. |
| schema.rs | The Zotero item-type schema — reference types (book, journalArticle, thesis, …), the fields each declares and base-field renames. |
| store.rs | On-disk persistence — the whole library round-trips through one versioned pretty-JSON file with an upgrade path. |
| search.rs | Library search — quick all-field text filter and condition-based saved searches sharing one matcher. |
| bib.rs | Built-in citation & bibliography formatting (APA / MLA / Chicago / IEEE) plus BibTeX cite-key generation. |
| csl.rs | A CSL 1.0.2 subset processor — load an arbitrary .csl stylesheet and render references through it, citeproc-style. |
| import.rs | Bibliographic import — BibTeX, RIS and CSL-JSON parsers mapping foreign records onto the item model. |
| export.rs | Bibliographic export — items rendered out to BibTeX, RIS and CSL-JSON. |
| xml_formats.rs | XML interchange (via quick-xml) — EndNote XML, MODS, MARCXML and Zotero RDF import/export. |
| identifier.rs | Identifier detection and metadata lookup — DOI (CrossRef), ISBN (Open Library) and PMID (NCBI). |
| pdf.rs | PDF text extraction for full-text indexing plus DOI/arXiv/ISBN recognition for "retrieve metadata for PDF". |
| duplicates.rs | Duplicate-item detection by shared DOI/ISBN or matching title+creator signals, for merge. |
| zotero.rs | Zotero Web API (v3) sync client — pull a user or group library as CSL-JSON via an API key. |
| webdav.rs | WebDAV transport — Zotero-style attachment-file sync: verify, upload, download and delete files. |
| ffi.rs | The C ABI for non-Rust hosts — a process-global engine behind a mutex, driven by zct_invoke. |
| tauri_plugin.rs | Tauri v2 integration — exposes the engine as ordinary app commands so any host embeds it. |
| util.rs | Dependency-free helpers — an RFC 4648 Base64 codec for ferrying attachment bytes across the JSON/FFI boundary, and small utilities. |
| error.rs | The engine Error/Result type, carrying a stable machine tag for FFI/Tauri serialization. |
~DEPENDENCY FOOTPRINT
Five foundational, vendorable dependencies; networking and PDF deps are optional features so the pure core builds in headless CI with no TLS or socket stack.
| Crate | Role | License |
|---|---|---|
| serde | Derive-based serialization of the library model. | MIT / Apache-2.0 |
| serde_json | The JSON command surface and on-disk store format. | MIT / Apache-2.0 |
| thiserror | The engine error type. | MIT / Apache-2.0 |
| dirs | Platform data/config directory resolution. | MIT / Apache-2.0 |
| quick-xml | Pull parser for EndNote XML / MODS / MARCXML / Zotero RDF. | MIT |
reqwest net | Blocking HTTP + native-tls for DOI/ISBN/PMID and Zotero/WebDAV sync. | MIT / Apache-2.0 |
lopdf pdf | Pure-Rust PDF text extraction and build (no native libs). | MIT |
tauri tauri | Tauri v2 host integration for the desktop app. | MIT / Apache-2.0 |
Pure Core
The five base crates carry no TLS or socket stack, so zcite-core compiles headless in CI with default features stripped.
Optional net
The default-on net feature pulls in reqwest for DOI/ISBN/PMID lookup and Zotero/WebDAV sync.
Optional pdf
The default-on pdf feature uses pure-Rust lopdf for text extraction — no native PDF libraries required.
Tauri host
The tauri feature gates the Tauri v2 integration so non-desktop hosts never compile it.
~VERIFICATION
The suite carries 239 tests in total — 78 unit tests living alongside the modules (#[test] / #[tokio::test] across schema, store, search, bib, csl, import, export, xml_formats, identifier, pdf, duplicates, zotero, webdav and util) plus 16 integration tests in tests/integration.rs that exercise the public Engine::invoke command surface end to end. Tests use no external fixtures — lopdf both builds and reads back the PDFs the pdf tests need — so the suite runs headless. Coverage against the full Zotero feature surface is hand-assessed conservatively in scripts/port_features.tsv and grep-verified against the real source; see the port report for the per-feature breakdown.
| Suite | Location | Tests | Coverage |
|---|---|---|---|
| Unit tests | #[test] / #[tokio::test] alongside modules | 195 | schema, store, search, bib, csl, import, export, xml_formats, identifier, pdf, duplicates, zotero, webdav, util |
| Integration tests | tests/integration.rs | 44 | public Engine::invoke command surface, end to end |
| Total | headless, no external fixtures | 239 | lopdf builds and reads back the PDFs the pdf tests need |