Read. Understand. Connect.
A calm, local-first reading workspace for PDFs and the ideas inside them.
CI · Specification · Contributing · Security
Shelf brings a focused PDF reader, reliable annotations, and a source-grounded AI companion into one portable application. Your documents and reading history stay under your control. Choose a local model, a cloud provider, or no AI at all.
- A reader first. Navigate, search, select, bookmark, highlight, and take notes without needing an AI provider or an internet connection.
- An AI companion when requested. Explain a passage, ask questions, summarize, or translate with explicit provider/model selection and traceable source references.
- A place to keep what matters. Preserve quotes, notes, reading progress, and later concepts with links back to the original document.
- A standalone product. No account or hosted service is required for core reading.
- Cross-platform by design. Windows, macOS, Linux, Android, and iOS are product targets, with native behavior behind platform adapters.
| Principle | Promise |
|---|---|
| Local-first | Reading data stays on the device by default. |
| Source-grounded AI | A citation is trusted only when it resolves to the supplied PDF source. |
| Provider choice | Local and cloud AI are both optional; the user controls remote context sharing. |
| Portable data | Reading progress and annotations can be exported in documented formats. |
| Reader-first UX | AI never blocks basic reading or annotation. |
| Platform honesty | A platform is supported only after its core workflows pass real target tests. |
Shelf is in its specification and foundation phase. The repository currently contains the product specification, delivery plan, project metadata, and development scaffolding—not a completed reader implementation.
The former TechShelf catalog is preserved under archive/ as historical input. It is not the new application's database schema.
- Reader Foundation — local PDF import, rendering, navigation, search, selection, annotations, and resume.
- AI Companion — local and cloud providers, bounded document context, citations, streaming, and cancellation.
- Knowledge & Portability — quote/note export, deep links, and reviewable concept/flashcard drafts.
- Standalone Release — validated Windows, macOS, Linux, Android, and iOS packages.
See the full specification and the work plan.
- TypeScript for the shared application core and platform-neutral contracts; shell-specific UI stays in small feature modules.
- Tailwind CSS is compiled into a local static asset at build time; it is not loaded from a runtime CDN.
- Mozilla PDF.js behind a Shelf-owned adapter.
- Go application services and SQLite for the initial desktop/local runtime.
- Capacitor and native adapters for mobile.
- Provider-neutral contracts for local and cloud inference.
These are implementation choices to validate against acceptance criteria; they are not claims of completed platform support.
| Path | Responsibility |
|---|---|
| apps/web/ | Shared web application and public static assets |
| apps/desktop/ | Desktop shell and packaging integration |
| apps/mobile/ | Mobile shell and native integration |
| packages/ | Reusable reader, PDF, annotation, and AI contracts |
| backend/ | Local application runtime, domain, ports, and adapters |
| spec/ | Product and engineering requirements |
| docs/ | Public project docs, developer guides, and ADRs |
| tests/ | Unit, integration, E2E tests, and PDF fixtures |
| archive/ | Preserved legacy catalog files |
Read Contributing, Development docs, and the Architecture specification before changing project structure.
The project uses PSX for repository structure conventions, GIX for Git flow, and Pipeline for the shared task graph and CI workflow.
Reader annotation use cases are shared from @shelf/reader-core; platform shells provide repository, ID, clock, and document-rendering adapters. Browser persistence is implemented by IndexedDB. Desktop/native implementations can reuse the exact use-case contract without importing browser APIs.
The optional Go backend mirrors the same domain/application/ports/adapter boundaries and provides SQLite and HTTP adapters for connected/desktop compositions. It is not required to use the local-first Web/PWA reader.