Architecture
Zinc is a desktop reference manager for Windows, Linux and macOS (Apple Silicon) that reads and writes a Zotero-format library kept in one SQLite file. The user interface, the core service that owns the database, and most background work run inside a single Bun process. A few things live outside that process: the Word add-in, the browser-connector host, and the web views used for web content. The Word add-in, the connector host and the sign-in helper are Windows only.
The diagram below shows the Windows build. On Linux and macOS the executable has no .exe, the PDF library is libzn_pdf.so or libzn_pdf.dylib, and the web views are GTK 4 with WebKitGTK 6 or WKWebView instead of WebView2.
This page is the map. Details are in Building, Testing, Database, HTTP API and Translators.
Overview
flowchart LR
subgraph proc["zotero-next-gpui.exe : one Bun process"]
ui["gpui-ui : Solid components drawn by GPUIX"]
core["core : handleApi, MCP, sync, import, cite, translate"]
svc["services.ts : Zotero port, sync, extract pool"]
wt["translate pool : Bun workers"]
wx["PDF extract pool : Bun workers"]
wp["prefetch worker"]
wd["document structure worker"]
ui <-->|"in-process calls, or loopback HTTP"| core
core --- svc
core --- wt
svc --- wx
ui --- wp
ui --- wd
end
db[("library.sqlite : WAL")]
core --> db
pdf["zn_pdf.dll : Rust, PDFium plus hayro"]
ui -->|"bun:ffi"| pdf
wv["WebView2 popups : reader-host, note-host"]
ui -->|"owned popup windows"| wv
wv -->|"served by core at /reader-host/ and /note-host/"| core
gpuix["GPUIX native addon : ABorakati/gpuix, branch zn-cache"]
ui --- gpuix
fx["fulltext.wasm : zotero-fulltext engine"]
core --- fx
api["port 23120 : /api and /mcp"]
zp["port 23119 : Zotero connector port"]
core --- api
svc --- zp
mcpc["MCP clients"] --> api
conn["Zotero Connector extension"] --> zp
word["Word add-in : C#, WebView2 sidebar"]
word -->|"read-only SQLite"| db
word -->|"optional HTTP"| api
agents["AI agents"] -->|"MCP on 23125"| word
host["connector-host : zotero-next-host.exe"]
ext["Zinc Connector extension"] -->|"native messaging"| host
host -->|"embeds core/src/connector"| db
Repository layout
| Path | What is in it |
|---|---|
gpui-ui/ |
The app: src/ (UI), native/pdf/ (Rust PDF library), scripts/ (build, package, AppImage, disk image, release, screenshot and benchmark scripts), installer/ (Inno Setup), UPDATES.md |
core/ |
The core service: src/ (database, migrations, HTTP API, MCP, sync, import and export, translators, citations), schema.sql, scripts/, test/, vendor/ (git-ignored) |
word/ |
addin/ (C# COM add-in, .NET Framework 4.8), sidebar/ (TypeScript sidebar and agent API), harness/ (test harness), build.ps1, install.ps1, uninstall.ps1 |
connector-host/ |
Native-messaging host for the browser connector (src/, test/, install.ps1, uninstall.ps1) |
reader-host/ |
Host page for Zotero’s web reader, used by snapshot and EPUB tabs (build.sh, src/, dist/) |
note-host/ |
Host page for Zotero’s note editor (build.sh, src/, dist/) |
vendor/ |
Upstream Zotero repositories cloned by the build scripts (document-worker, reader, note-editor). Git-ignored |
scripts/ |
build-docworker.sh and shims/ |
website/ |
Project website sources (Astro): product pages and the docs |
docs/ |
Documentation: user-guide/, developer-guide/, screenshots/ |
data/ |
A local library kept by a developer. Git-ignored; never commit or script against it |
.github/workflows/ |
ci.yml, fuzz-nightly.yml, macos.yml, desktop-packages.yml, web.yml (the website and its demo, deployed to GitHub Pages) and extension.yml (the browser extension) |
The old Electrobun app (app/, ui/) is not part of this documentation.
The app process
gpui-ui/src/main.tsx is the entry point. It renders a splash screen first, registers fonts, and only then imports the heavy modules (the app, the store, the core), so the window appears before the core has loaded.
Entry layout and the .web.ts rule
The desktop app, the browser extension’s library page and the web page all start from src/main.tsx, so they cannot drift apart. The start-up is split in three:
| File | Holds |
|---|---|
src/main.tsx |
Imports the platform module first, then calls start(platform). |
src/start.tsx |
The start-up steps, in one fixed order, with their trace marks (mark(...), read by scripts/startup.ts): appearance, splash, render(), fonts, connect the data, store, bindUiState, startAppearance, App, first items, features. Also the Platform interface. |
src/platform.ts |
The desktop: the four side-effect imports (linuxDisplay, uvpool, signin/entry, packaged), the error log, the prefetch worker, fonts, the in-process core, the window theme and icon, reveal requests, updates, the crash toast. |
src/platform.web.ts |
The browser: the data path, the file fetcher for PDFs, the probes the headless checks read (znLibrary, znPdfStats, znDemo), the welcome screen, the move offer, ?select=, outside-change handling. |
platform.web.ts picks the data path when the page loads. An extension page uses the native host, or, with ?mode=browser, the browser library over a zinc-db port. A plain web page is a read-only showcase: it always runs the in-memory demo library (web/page-source.ts), where every write answers 403 and My Library is marked not editable so the app hides its edit actions. Nothing is saved and there is no sync; the Zinc Connector is the browser product that keeps a library.
The rule. web/build.ts builds both browser targets from src/main.tsx. When a relative import resolves to X.ts or X.tsx and X.web.ts or X.web.tsx sits next to it, the browser builds use the sibling. Bun on the desktop never looks for .web files, and tsc checks them with everything else. Today there are three: platform.web.ts, reader/pdf.web.ts (PDFium WebAssembly in place of zn_pdf.dll) and reader/structure/load.web.ts (the document worker as a Web Worker). To make a module differ in the browser, add the sibling with the same exports; do not add a branch to the shared file. Build-time constants (__ZN_EXTENSION__, __ZN_DOCWORKER__, set in web/build.ts) drop code a target does not use.
The UI is TypeScript with Solid components. GPUIX (a Solid adapter for Zed’s GPUI) draws it natively; there is no browser engine in the main window. Features plug into the shell through the registry in gpui-ui/src/registry.ts (item actions, app actions, overlays, sidebar sections, settings sections); see Contributing.
Core in the same process
gpui-ui/src/core.ts decides where the core runs:
| Setting | Behaviour |
|---|---|
ZN_DB=<library copy> |
The app starts the core itself on that database and starts an HTTP server on loopback. |
ZN_DB plus ZN_CORE_DIRECT=1 |
No HTTP at all. gpui-ui/src/api.ts calls the core’s handleApi(Request, db) directly. Nothing else (MCP, connector, a browser) can reach the core, and web tabs and the web note editor are off. |
| neither | An external core at ZN_URL (default http://127.0.0.1:23160). |
| packaged exe | Always runs the core in-process. The database comes from core/src/library-location.ts (see Database). |
Settings, state files and the default library go in per-OS folders chosen by core/src/platform-dirs.ts: %APPDATA% on Windows, ~/Library/Application Support on macOS, and on Linux $XDG_CONFIG_HOME (~/.config) for settings and $XDG_DATA_HOME (~/.local/share) for data. An explicit APPDATA wins on every OS, which tests rely on.
The core writes to its database. An unpackaged run refuses the real library path unless ZN_ALLOW_REAL_DB=1; use a VACUUM INTO copy for development.
Ports
| Port | Owner | Purpose |
|---|---|---|
| 23120 | core/src/server.ts |
The core HTTP API under /api, the MCP endpoint /mcp, and static mounts /reader-host/ and /note-host/. Default for the packaged app; an unpackaged in-process run defaults to 23161 (ZN_PORT overrides). If the wanted port is taken, the core takes a free loopback port and leaves sync and port 23119 to the other instance. |
| 23119 | core/src/zport/index.ts |
The Zotero-compatible “Zotero port” for the Zotero Connector extension and Better BibTeX endpoints. Started by gpui-ui/src/services.ts, only while Zotero itself is not holding the port, retried every 30 seconds. |
| 23125 | word/addin/McpServer.cs |
The Word add-in’s own MCP server (setting mcpPort, default 23125; mcpEnabled, default on). Separate from the core’s /mcp. |
Details of the routes are in HTTP API.
Services
gpui-ui/src/services.ts runs in the packaged app (or with ZN_SERVICES=1): the Zotero port, two-way sync with the local Zotero library, the PDF text-extraction pool, the native folder dialog for Settings, and clean shutdown. ZN_SYNC=0 and ZN_ZPORT=0 turn two of them off.
Worker threads
| Worker | Source | Notes |
|---|---|---|
| Translate pool | core/src/translate/pool.ts, worker.ts |
Runs Zotero translators. Up to 2 workers, one job at a time each, 60 s default timeout, replaced after a timeout or 50 jobs. See Translators. |
| PDF extract pool | core/src/extract/pool.ts, pdf-worker.ts |
Runs Zotero’s document-worker (pdf.js) for full-text extraction. Hard per-job timeout, workers recycled after 40 jobs. |
| Prefetch worker | gpui-ui/src/prefetch.ts, prefetch-worker.ts |
Answers the first screen’s GET requests from a read-only connection while the main thread creates the window. Needs ZN_DB; ZN_PREFETCH=0 turns it off. |
| Document-structure worker | gpui-ui/src/reader/structure/worker.ts, docworker-entry.ts |
Runs Zotero’s document-worker for the reading view (citations, figures, layout). |
PDF rendering: gpui-ui/native/pdf
A Rust cdylib (zn_pdf) that renders pages with PDFium (loaded at run time from pdfium.dll, libpdfium.so or libpdfium.dylib) and uses the pure-Rust hayro crate for the text layer, links and outline. hayro also renders when PDFium cannot be loaded (ZN_PDF_BACKEND=hayro forces it). The app loads zn_pdf.dll (libzn_pdf.so, libzn_pdf.dylib) through bun:ffi in gpui-ui/src/reader/pdf.ts; rendering jobs run on Rust worker threads and are polled from JS so the UI thread is never blocked. See Building for how the DLL is built.
Web view pages
GPUIX has no web-view element, so the few places that need web content use a native web view through webview-bun: WebView2 on Windows, WebKitGTK 6 on Linux and WKWebView on macOS. gpui-ui/src/webview/host.ts creates each web view in a popup window owned by the main window (a frameless one on Windows) and keeps it positioned over a placeholder element. Nothing is created until first use and it is destroyed on release, because the WebView2 processes cost roughly 100 to 200 MB.
The OS calls for placing the popup are picked once in gpui-ui/src/webview/popup.ts: win32.ts on Windows, x11.ts on Linux and cocoa.ts on macOS. Each loads its libraries lazily.
- Linux. The web view is a GTK 4 window over the app window, which only works when both are X11 windows.
gpui-ui/src/shell/linuxDisplay.tsruns first inmain.tsxand moves the app to X11 (XWayland on a Wayland desktop) before GPUIX loads.ZN_WAYLAND=1keeps native Wayland, with no web view. The same file turns off GTK’s desktop portal for printing outside Flatpak, because the portal can hang where it has no dialog to show (WSLg). - macOS. The
WKWebViewis reparented into GPUI’s own view (cocoa.ts, with Objective-C calls throughgpui-ui/src/shell/objc.ts). - Printing. Linux prints through the GTK dialog and CUPS (
gpui-ui/src/reader/printGtk.ts), macOS through PDFKit (gpui-ui/src/reader/printMac.ts).
| Page | Directory | Served at | Used for |
|---|---|---|---|
| Reader host | reader-host/ |
/reader-host/ |
Web tabs: HTML snapshots and EPUBs, in Zotero’s web reader (WebTabView.tsx) |
| Note host | note-host/ |
/note-host/ |
Zotero’s note editor in the item pane (gpui-ui/src/webview/notes.ts) |
gpui-ui/src/webview/mounts.ts registers the two static mounts on the core server. If a dist/ folder is missing, that mount is left out and the feature falls back (web tabs open in the default app; notes use the built-in Markdown editor). Both builds need the upstream clones under vendor/, built by reader-host/build.sh and note-host/build.sh.
The core: core/
core/src/api.ts is the request router; core/src/server.ts wraps it in Bun.serve. Feature areas have their own folders and route modules: additems/, bbt/ (Better BibTeX), cite/ (citation styles and formatting), duplicates/, files/, fulltext/ (Find Full Text), import/ and io/, integrations/, maintenance/, references/, searches/, sync/ (local Zotero), websync/ (zotero.org), translate/, update/ (auto-update logic), mcp/, connector/ and zport/.
Full-text engine
Find Full Text runs the zotero-fulltext engine as a WebAssembly module (core/src/fulltext/wasm.ts loads core/vendor/fulltext-wasm/fulltext.wasm; host.ts is the Bun host that performs the engine’s effects). The engine is built in a separate private repository (ABorakati/zotero-fulltext) and is not in this repo. A fresh checkout needs at least an empty placeholder file at that path; see Building and Testing.
SQLite library
One SQLite file in WAL mode holds items (as Zotero Web API JSON plus query columns), collections, tags, annotations, the sync outbox and settings state. See Database.
The GPUIX fork
On Windows the app runs a locally built @gpuix/native addon instead of the npm 0.11.0 binary. (Linux and macOS use the npm binary.) It adds a cacheRegion style key so that unchanged regions (sidebar, toolbar, item pane) are replayed instead of rebuilt when only the list scrolls. The source is the private repository ABorakati/gpuix, branch zn-cache. The addon is copied over the npm binary by hand after every bun install; without it the app still works with whole-window redraws. Instructions are in gpui-ui/scripts/README.md (“Custom GPUIX native addon”) and summarised in Building.
Word add-in: word/
Windows only.
| Part | Technology | Role |
|---|---|---|
word/addin/ |
C#, .NET Framework 4.8, COM add-in (no VSTO runtime, no admin rights) | Registers with Word per user, hosts the sidebar in a Custom Task Pane, reads the library read-only through winsqlite3.dll (Sqlite.cs, Library.cs), and runs the MCP server (McpServer.cs) |
word/sidebar/ |
TypeScript, bundled by build.ts |
The sidebar UI (main.ts), the popup, and the agent API (agent-main.ts) that executes MCP tools in a hidden WebView2 (AgentHost.cs) |
word/harness/ |
C# | Test harness used by the end-to-end tests |
The add-in finds the library with the same rule as core/src/library-location.ts (word/addin/Settings.cs mirrors it). The link to a running app is optional (ZnClient.cs, default http://127.0.0.1:23120). The MCP server requires a bearer token stored per user and refuses requests that carry an Origin header.
Browser connector host: connector-host/
Windows only.
zotero-next-host.exe is a Bun-compiled native-messaging host started by Chrome or Edge for the Zinc Connector extension (a fork kept in a separate repository). It embeds core/src/connector and runs the same connector handlers as port 23119 directly against the library database, so saving works with the app closed. It is registered per user in HKCU by connector-host/install.ps1. Protocol framing is in connector-host/src/frames.ts.
Open in Zinc: showing an item from outside the app
The Word sidebar and the browser connector’s popup can ask the running app to show an item. The routes are in HTTP API.
- The request. The Word add-in (
word/addin/ZnClient.cs,Reveal) starts the app if it is not running, waits up to about 40 seconds for its API, and postsPOST /api/ui/revealwith{key, open: true}. The connector host (connector-host/src/reveal.ts) also posts reveal requests. The core keeps the latest one in memory with a sequence number (core/src/connector/state.ts). Withopen: trueit also picks the item’s readable attachment (the one asked for, else the PDF, else the EPUB, else the HTML snapshot). - Raising the window. The app does not raise its own window. After a successful post the add-in does it (
BringToFront): it looks for a visible window titledZincand of classZed::Window(the GPUI app;BasicWindowClassis the old app), restores it if minimised and brings it forward. - The poll. The app polls
GET /api/ui/selectionevery 1.5 seconds (gpui-ui/src/shell/revealRequests.ts) and acts whenreveal.seqchanges. A request that is more than 60 seconds old when the app first looks is ignored. - A file. If the request carries
open,gpui-ui/src/platform.tsselects the item and opens that attachment in the reader. - No file. Otherwise it calls
store.revealItem(key)(gpui-ui/src/store.ts). That finds the item’s row: in the rows already loaded, or else throughGET /api/items/indexwith the list’s current query. When the item is not in this view it switches to My Library with no search or filter and asks again. If even My Library does not list it, it gives up and returnsfalse. Otherwise it selects the item and setsscrollRequest({index, seq}). The duplicates view and full-text results are not plain listings, so they always switch to My Library. - The scroll.
gpui-ui/src/table/Table.tsxandgpui-ui/src/cards/CardList.tsxfollowscrollRequest. The new list is still arriving (its row count, then the group headers that move every row down), so forREVEAL_SETTLE_MS(3 seconds) after a request they scroll again each time the row count changes.
gpui-ui/scripts/shot-reveal.tsx checks the last two steps headlessly; see Testing.