# wangqrkkk/paperquay architecture

> Architecture diagram of the GitHub repository wangqrkkk/paperquay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wangqrkkk/paperquay
- Repository: https://github.com/wangqrkkk/paperquay

## Overview

PaperQuay is a local-first desktop workspace for managing and understanding research papers. Users import or organize papers, open them in the reader, inspect structured content, translate or ask questions, and keep notes; optional Zotero, Agent, review-writing, knowledge-graph, and backup workflows extend that core. The renderer’s workspaces call services and cross the Electron boundary for local files and persistence. README statements support the product-level branches; source excerpts and the index support only the specific implementation links shown. Several backend and workspace implementations were not sampled, so their internal connections are omitted.

Main entry points: [`src/app/App.tsx`](https://github.com/wangqrkkk/paperquay/blob/main/src/app/App.tsx) (App shell), [`src/features/reader/Reader.tsx`](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/Reader.tsx) (Reader workspace), [`src/features/reader/useReaderLibraryPreview.ts`](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/useReaderLibraryPreview.ts) (Preview workflow), [`src/platform/electron/core.ts`](https://github.com/wangqrkkk/paperquay/blob/main/src/platform/electron/core.ts) (Electron IPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["App shell<br/>[App.tsx]"]
  node_notes["Notes workspace<br/>[NotesWorkspace.tsx]"]
end

subgraph group_reading["Reading and AI"]
  node_reader["Reader workspace<br/>[Reader.tsx]"]
  node_reader_actions["Reader actions"]
  node_preview["Library preview"]
  node_reader_preview_hook["Preview workflow"]
  node_mineru["MinerU parsing<br/>[mineru.ts]"]
  node_translation["Translation"]
  node_rag["Local RAG<br/>[localRag.ts]"]
end

subgraph group_library["Library and storage"]
  node_library_ui["Literature library"]
  node_library_service["Library service<br/>[library.ts]"]
  node_notes_service["Notes service<br/>[notes.ts]"]
  node_notes_store["Notes store<br/>[useNotesStore.ts]"]
end

subgraph group_research["Research tools"]
  node_agent["Agent workspace<br/>[AgentWorkspace.tsx]"]
  node_agent_service["Agent tools<br/>[libraryAgent.ts]"]
  node_graph["Knowledge graph"]
  node_review["Review writing"]
  node_review_service["Review generation<br/>[reviewWriting.ts]"]
  node_zotero["Zotero integration<br/>[zoteroCommands.cjs]"]
end

subgraph group_desktop["Desktop runtime"]
  node_library_commands["Library commands"]
  node_library_db[("Library database")]
  node_backup["WebDAV backup<br/>[webdavCommands.cjs]"]
  node_electron_main["Electron main<br/>[main.cjs]"]
  node_backend["Backend router<br/>[backend.cjs]"]
  node_desktop_api["Desktop API<br/>[desktop.ts]"]
  node_ipc["Electron IPC<br/>[core.ts]"]
end

node_user(("Researcher"))
node_external_ai(("AI provider"))
node_webdav(("WebDAV server"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_reader
node_app -->|"renders"| node_agent
node_app -->|"opens workspace"| node_notes
node_app -->|"opens workspace"| node_graph
node_app -->|"opens workspace"| node_review
node_reader -.->|"uses"| node_reader_actions
node_reader -.->|"loads previews"| node_reader_preview_hook
node_reader_preview_hook -->|"loads and caches"| node_preview
node_reader_preview_hook -->|"updates paper"| node_library_service
node_reader_preview_hook -->|"requests summary"| node_external_ai
node_reader_actions -.->|"parses PDF"| node_mineru
node_reader_actions -->|"translates blocks"| node_translation
node_reader -.->|"uses retrieval"| node_rag
node_user -->|"imports and organizes"| node_library_ui
node_library_ui -.->|"manages papers"| node_library_service
node_library_service -->|"invokes desktop"| node_ipc
node_ipc -.->|"sends IPC"| node_electron_main
node_electron_main -->|"loads backend"| node_backend
node_backend -.->|"routes commands"| node_library_commands
node_library_commands -.->|"persists library"| node_library_db
node_notes -.->|"edits notes"| node_notes_store
node_notes_store -->|"loads and saves"| node_notes_service
node_notes_service -->|"invokes desktop"| node_ipc
node_agent -.->|"uses tools"| node_agent_service
node_agent -->|"assists management"| node_library_ui
node_review -->|"generates draft"| node_review_service
node_review_service -->|"invokes commands"| node_ipc
node_user -->|"imports library"| node_zotero
node_user -.->|"backs up data"| node_backup
node_backup -.->|"syncs backup"| node_webdav
node_user -->|"configures provider"| node_external_ai

click node_app "https://github.com/wangqrkkk/paperquay/blob/main/src/app/App.tsx"
click node_reader "https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/Reader.tsx"
click node_reader_actions "https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/useReaderLibraryActions.ts"
click node_preview "https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/readerLibraryPreview.ts"
click node_reader_preview_hook "https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/useReaderLibraryPreview.ts"
click node_mineru "https://github.com/wangqrkkk/paperquay/blob/main/src/services/mineru.ts"
click node_translation "https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/readerTranslation.ts"
click node_rag "https://github.com/wangqrkkk/paperquay/blob/main/src/services/localRag.ts"
click node_library_ui "https://github.com/wangqrkkk/paperquay/blob/main/src/features/literature/LiteratureLibraryView.tsx"
click node_library_service "https://github.com/wangqrkkk/paperquay/blob/main/src/services/library.ts"
click node_library_commands "https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/libraryCommands.cjs"
click node_library_db "https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/libraryDatabaseStore.cjs"
click node_notes "https://github.com/wangqrkkk/paperquay/blob/main/src/features/notes/NotesWorkspace.tsx"
click node_notes_service "https://github.com/wangqrkkk/paperquay/blob/main/src/services/notes.ts"
click node_notes_store "https://github.com/wangqrkkk/paperquay/blob/main/src/stores/useNotesStore.ts"
click node_agent "https://github.com/wangqrkkk/paperquay/blob/main/src/features/agent/AgentWorkspace.tsx"
click node_agent_service "https://github.com/wangqrkkk/paperquay/blob/main/src/services/libraryAgent.ts"
click node_graph "https://github.com/wangqrkkk/paperquay/blob/main/src/features/graph/KnowledgeGraphWorkspace.tsx"
click node_review "https://github.com/wangqrkkk/paperquay/blob/main/src/features/review/ReviewWritingWorkspace.tsx"
click node_review_service "https://github.com/wangqrkkk/paperquay/blob/main/src/services/reviewWriting.ts"
click node_zotero "https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/zoteroCommands.cjs"
click node_backup "https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/webdavCommands.cjs"
click node_electron_main "https://github.com/wangqrkkk/paperquay/blob/main/electron/main.cjs"
click node_backend "https://github.com/wangqrkkk/paperquay/blob/main/electron/backend.cjs"
click node_desktop_api "https://github.com/wangqrkkk/paperquay/blob/main/src/services/desktop.ts"
click node_ipc "https://github.com/wangqrkkk/paperquay/blob/main/src/platform/electron/core.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_notes toneBlue
class node_reader,node_reader_actions,node_preview,node_reader_preview_hook,node_mineru,node_translation,node_rag toneAmber
class node_library_ui,node_library_service,node_notes_service,node_notes_store,node_webdav toneMint
class node_agent,node_agent_service,node_graph,node_review,node_review_service,node_zotero toneRose
class node_library_commands,node_library_db,node_backup,node_electron_main,node_backend,node_desktop_api,node_ipc,node_user,node_external_ai toneIndigo
```

## Components

### Workspace UI

- [App shell](https://github.com/wangqrkkk/paperquay/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Notes workspace](https://github.com/wangqrkkk/paperquay/blob/main/src/features/notes/NotesWorkspace.tsx): `src/features/notes/NotesWorkspace.tsx`

### Reading and AI

- [Reader workspace](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/Reader.tsx): `src/features/reader/Reader.tsx`
- [Reader actions](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/useReaderLibraryActions.ts): `src/features/reader/useReaderLibraryActions.ts`
- [Library preview](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/readerLibraryPreview.ts): `src/features/reader/readerLibraryPreview.ts`
- [Preview workflow](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/useReaderLibraryPreview.ts): `src/features/reader/useReaderLibraryPreview.ts`
- [MinerU parsing](https://github.com/wangqrkkk/paperquay/blob/main/src/services/mineru.ts): `src/services/mineru.ts`
- [Translation](https://github.com/wangqrkkk/paperquay/blob/main/src/features/reader/readerTranslation.ts): `src/features/reader/readerTranslation.ts`
- [Local RAG](https://github.com/wangqrkkk/paperquay/blob/main/src/services/localRag.ts): `src/services/localRag.ts`

### Library and storage

- [Literature library](https://github.com/wangqrkkk/paperquay/blob/main/src/features/literature/LiteratureLibraryView.tsx): `src/features/literature/LiteratureLibraryView.tsx`
- [Library service](https://github.com/wangqrkkk/paperquay/blob/main/src/services/library.ts): `src/services/library.ts`
- [Notes service](https://github.com/wangqrkkk/paperquay/blob/main/src/services/notes.ts): `src/services/notes.ts`
- [Notes store](https://github.com/wangqrkkk/paperquay/blob/main/src/stores/useNotesStore.ts): `src/stores/useNotesStore.ts`

### Research tools

- [Agent workspace](https://github.com/wangqrkkk/paperquay/blob/main/src/features/agent/AgentWorkspace.tsx): `src/features/agent/AgentWorkspace.tsx`
- [Agent tools](https://github.com/wangqrkkk/paperquay/blob/main/src/services/libraryAgent.ts): `src/services/libraryAgent.ts`
- [Knowledge graph](https://github.com/wangqrkkk/paperquay/blob/main/src/features/graph/KnowledgeGraphWorkspace.tsx): `src/features/graph/KnowledgeGraphWorkspace.tsx`
- [Review writing](https://github.com/wangqrkkk/paperquay/blob/main/src/features/review/ReviewWritingWorkspace.tsx): `src/features/review/ReviewWritingWorkspace.tsx`
- [Review generation](https://github.com/wangqrkkk/paperquay/blob/main/src/services/reviewWriting.ts): `src/services/reviewWriting.ts`
- [Zotero integration](https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/zoteroCommands.cjs): `electron/backend/zoteroCommands.cjs`

### Desktop runtime

- [Library commands](https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/libraryCommands.cjs): `electron/backend/libraryCommands.cjs`
- [Library database](https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/libraryDatabaseStore.cjs): `electron/backend/libraryDatabaseStore.cjs`
- [WebDAV backup](https://github.com/wangqrkkk/paperquay/blob/main/electron/backend/webdavCommands.cjs): `electron/backend/webdavCommands.cjs`
- [Electron main](https://github.com/wangqrkkk/paperquay/blob/main/electron/main.cjs): `electron/main.cjs`
- [Backend router](https://github.com/wangqrkkk/paperquay/blob/main/electron/backend.cjs): `electron/backend.cjs`
- [Desktop API](https://github.com/wangqrkkk/paperquay/blob/main/src/services/desktop.ts): `src/services/desktop.ts`
- [Electron IPC](https://github.com/wangqrkkk/paperquay/blob/main/src/platform/electron/core.ts): `src/platform/electron/core.ts`

### Other components

- **Researcher**
- **AI provider**
- **WebDAV server**

## Connections

- Researcher → App shell: uses (evidence: `README.md`)
- App shell → Reader workspace: renders (evidence: `src/app/App.tsx`)
- App shell → Agent workspace: renders (evidence: `src/app/App.tsx`)
- App shell → Notes workspace: opens workspace (evidence: `README.md`)
- App shell → Knowledge graph: opens workspace (evidence: `src/app/App.tsx`)
- App shell → Review writing: opens workspace (evidence: `src/app/App.tsx`)
- Reader workspace → Reader actions: uses
- Reader workspace → Preview workflow: loads previews
- Preview workflow → Library preview: loads and caches (evidence: `src/features/reader/useReaderLibraryPreview.ts`)
- Preview workflow → Library service: updates paper (evidence: `src/features/reader/useReaderLibraryPreview.ts`)
- Preview workflow → AI provider: requests summary (evidence: `src/features/reader/useReaderLibraryPreview.ts`)
- Reader actions → MinerU parsing: parses PDF (evidence: `src/features/reader/useReaderLibraryActions.ts`)
- Reader actions → Translation: translates blocks (evidence: `src/features/reader/useReaderLibraryActions.ts`)
- Reader workspace → Local RAG: uses retrieval
- Researcher → Literature library: imports and organizes (evidence: `README.md`)
- Literature library → Library service: manages papers
- Library service → Electron IPC: invokes desktop (evidence: `src/services/library.ts`)
- Electron IPC → Electron main: sends IPC
- Electron main → Backend router: loads backend (evidence: `electron/main.cjs`)
- Backend router → Library commands: routes commands
- Library commands → Library database: persists library
- Notes workspace → Notes store: edits notes
- Notes store → Notes service: loads and saves (evidence: `src/stores/useNotesStore.ts`)
- Notes service → Electron IPC: invokes desktop (evidence: `src/services/notes.ts`)
- Agent workspace → Agent tools: uses tools
- Agent workspace → Literature library: assists management (evidence: `README.md`)
- Review writing → Review generation: generates draft (evidence: `src/features/review/ReviewWritingWorkspace.tsx`)
- Review generation → Electron IPC: invokes commands (evidence: `src/services/reviewWriting.ts`)
- Researcher → Zotero integration: imports library (evidence: `README.md`)
- Researcher → WebDAV backup: backs up data
- WebDAV backup → WebDAV server: syncs backup
- Researcher → AI provider: configures provider (evidence: `README.md`)
