- Published on
Zotero iOS System Design
- Authors

- Name
- Vishal V
- @VishalVignesh_
Product for Knowledge Power Users
I love Zotero.
I’ve been using it for a while now, and it has quietly become one of the most important tools in how I think and work. I originally started using it during my thesis project in college, but over time I realized it extends beyond academic work to anyone who needs to gather, organize, and revisit information from multiple sources.
What makes Zotero powerful is how naturally it fits into a research workflow. I can:
- grab a web page instantly using the Zotero connector
- pull research papers directly from sources like Google Scholar
- store PDFs, books, and documents from anywhere
- annotate, organize, and tag everything in one place
It essentially becomes a central repository of knowledge assets, the underlying source material.
What made it even more useful for me was how well it integrates with tools like Obsidian. Zotero acts as the source layer, while Obsidian becomes the thinking layer. One holds the raw material. The other builds connections and ideas. But importantly, Zotero doesn’t need Obsidian. On its own, it can function as a complete knowledge base, storing and structuring everything you consume.
That dual nature of standalone capability and composability with other tools is what makes Zotero a genuinely strong product.
Pain Point
The main friction I’ve faced with Zotero is storage.
The free tier gives you 300 MB, which fills up surprisingly fast once you start storing PDFs, papers, and books. Beyond that, you need to pay for additional storage tiers.
There are valid reasons for this:
- running a cloud service has real costs
- subscriptions support the team maintaining the product
But as a user, especially given that Zotero is open source, it introduces friction into what is otherwise a very smooth workflow.
From a user perspective, this kind of tool ideally feels like:
invisible infrastructure, always available, never blocking you
And this is where I found a contrast with some other exceptional OS tools.
Tools like Obsidian allow you to:
- use local storage
- optionally sync via iCloud or other providers
Zotero, on the other hand, leans more toward:
- its own cloud as the primary sync layer
For Apple users especially, this raises a natural question:
If iCloud already exists as a storage and sync layer, why not leverage it directly?
System Design and Code
Zotero iOS is the mobile client for the Zotero research ecosystem.
Architecture:
- UIKit app with scene-based lifecycle (AppDelegate, SceneDelegate)
- Navigation coordinated by AppCoordinator
- Split-view shell (MainViewController) for libraries, collections, items, and readers
Core system:
- Controllers.swift is the central dependency graph
- Handles API, session, storage, sync, background tasks, and lifecycle
- Session layer wires sync, WebDAV, attachment upload/download, background uploads, websocket updates, PDF worker, and cleanup
Other signals:
- share extension (ZShare) for external capture/import
- submodules (reader, pdf-worker, translators, etc.) act as integration layer
- mixed state management (Combine + RxSwift + SwiftUI bindings)
File storage:
- sits at the core of the system
- drives sync, upload, download, and access
Storage Model Design
Attachment storage assumes a single root directory. All file paths are derived from this base. Sync and file handling logic depend on this assumption.
Tradeoff
Moving from a single storage system to multiple storage backends introduces flexibility for the user. It also increases complexity in file handling.
Risks
Changing path resolution affects the entire system. Sync assumptions no longer hold in the same way. More edge cases appear in download, offline behavior, and file access. The user mental model becomes unclear.