>_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), 199 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
Fifty-two 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 (199 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. |
| attest.rs | Quote & locator attestation — proving a manuscript's quotations against the cited PDFs. |
| decompile.rs | Style-inverse decompiler — reads a finished manuscript back into CSL items. |
| oplog.rs | The append-only operation log behind serverless library sync. |
| crdt.rs | Conflict-free merge of library operations — the half that makes serverless sync work. |
| sync.rs | Serverless library sync — the orchestration over oplog and crdt. |
| docmerge.rs | Citation-aware structural 3-way merge for co-authored word-processor documents. |
| stylefit.rs | Citation style-fit audit (a zcite original) — per-style citation renderability. |
| styledelta.rs | Citation style-diff (a zcite original) — the switch-style impact preview. |
| cite_syntax.rs | Position-aware citation extraction across manuscript syntaxes — the input layer. |
| rtfscan.rs | RTF Scan — resolves free-text citation markers against the library. |
| lsp.rs | zcite-lsp — the reference manager exposed as a citation Language Server. |
| integrity.rs | Library integrity checking, in the shape of JabRef's "Check Integrity". |
| analytics.rs | Library analytics — timeline, aggregate statistics and a tag cloud. |
| journal.rs | Offline ISO 4 / LTWA-style journal-title abbreviation. |
| refgraph.rs | Second-order citation mining — reads the reference list out of each attached PDF and builds the graph of what your sources cite. |
| provenance.rs | Sentence-level citation provenance (a zcite original) — walks a claim from the draft sentence into the cited work's prose, follows the marker printed on the sentence that carries it through that work's own reference list, and repeats until a sentence asserts the claim instead of attributing it. |
| drift.rs | Claim drift along a provenance chain (a zcite original) — reads the chain evidence-first and compares each restatement against the one below it on certainty, scope and quantity, naming which document first stated the claim more firmly than its source did. |
| commands.rs | The command name table behind Engine::invoke (199 entries). |
| Plus backup, cleanup, cluster, csv, fidelity, locale, markdown, metadata, names, network, quality, reports, tex, textproc and wordproc — 54 modules in all. | |
~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 404 tests in total — 352 unit tests living alongside the modules (#[test] / #[tokio::test] across schema, store, search, bib, csl, import, export, xml_formats, identifier, pdf, duplicates, provenance, zotero, webdav and util), 49 integration tests in tests/integration.rs that exercise the public Engine::invoke command surface end to end, and 3 in tests/lsp_stdio.rs that drive the shipped zcite-lsp binary over real stdio. 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 crates/zcite-core/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 | 352 | schema, store, search, bib, csl, import, export, xml_formats, identifier, pdf, duplicates, provenance, zotero, webdav, util |
| Integration tests | tests/integration.rs | 49 | public Engine::invoke command surface, end to end |
| LSP wire tests | tests/lsp_stdio.rs | 3 | the shipped zcite-lsp binary, driven over real stdio |
| Total | headless, no external fixtures | 404 | lopdf builds and reads back the PDFs the pdf tests need |