# steven-jianhao-li/zotero-ai-butler architecture

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

- Interactive diagram: https://gitdiagram.com/steven-jianhao-li/zotero-ai-butler
- Repository: https://github.com/steven-jianhao-li/zotero-ai-butler

## Overview

Zotero AI Butler is a Zotero plugin for analyzing papers and managing AI-generated research artifacts. Users trigger analysis manually, through automatic scanning, or by selecting unprocessed library items; tasks are queued, paper content is extracted, and configured language models generate notes and other outputs. The plugin also provides deep reading, literature reviews, image summaries, mind maps, and an in-reader note/chat experience. The graph combines README-documented capabilities with sampled source references; several feature implementations were not excerpted, so their internal links are omitted.

Main entry points: [`src/modules/taskQueue.ts`](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/taskQueue.ts) (Task queue), [`src/modules/noteGenerator.ts`](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/noteGenerator.ts) (Note generation), [`src/modules/llmService.ts`](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/llmService.ts) (LLM middleware), [`src/modules/views/MainWindow.ts`](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/MainWindow.ts) (Main window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Zotero entry"]
  node_startup["Plugin startup<br/>[addon.ts]"]
  node_hooks["Zotero hooks<br/>[hooks.ts]"]
end

subgraph group_workflow["Paper workflow"]
  node_taskqueue["Task queue<br/>[taskQueue.ts]"]
  node_autoscan["Automatic scanning<br/>[autoScanManager.ts]"]
  node_extract["Content extraction"]
  node_pdf["PDF extraction<br/>[pdfExtractor.ts]"]
  node_notes["Note generation<br/>[noteGenerator.ts]"]
  node_noteformat["Note formatting<br/>[noteMarkdown.ts]"]
  node_notestore[("Zotero notes<br/>[aiNoteService.ts]")]
end

subgraph group_models["Model services"]
  node_llmservice["LLM middleware<br/>[llmService.ts]"]
  node_endpoints["Endpoint management"]
  node_providers["Provider implementations"]
end

subgraph group_features["Research features"]
  node_deepread["Deep reading<br/>[deepReadEngine.ts]"]
  node_review["Literature reviews"]
  node_image["Image summaries"]
  node_mindmap["Mind maps<br/>[mindmapService.ts]"]
end

subgraph group_interface["Plugin interface"]
  node_pane["Reader sidebar<br/>[ItemPaneSection.ts]"]
  node_mainwindow["Main window<br/>[MainWindow.ts]"]
  node_summaryview["Summary view<br/>[SummaryView.ts]"]
  node_reviewview["Review view"]
  node_preferences[("Preferences<br/>[prefs.ts]")]
  node_prompts["Prompt management<br/>[prompts.ts]"]
end

node_researcher(("Researcher"))
node_zotero["Zotero library"]
node_modelservice{{"Configured model API"}}

node_researcher -->|"adds papers"| node_zotero
node_zotero -->|"triggers plugin"| node_hooks
node_hooks -->|"enqueues analysis"| node_taskqueue
node_hooks -->|"opens dashboard"| node_mainwindow
node_autoscan -->|"enqueues papers"| node_taskqueue
node_taskqueue -->|"requests content"| node_extract
node_extract -->|"extracts PDFs"| node_pdf
node_taskqueue -->|"runs summaries"| node_notes
node_notes -.->|"requests generation"| node_llmservice
node_notes -.->|"formats output"| node_noteformat
node_taskqueue -->|"runs image summary"| node_image
node_taskqueue -->|"runs mind maps"| node_mindmap
node_taskqueue -->|"runs reviews"| node_review
node_reviewview -->|"configures reviews"| node_review
node_mainwindow -->|"shows summary"| node_summaryview
node_mainwindow -->|"shows reviews"| node_reviewview
node_pane -->|"shows AI notes"| node_notestore
node_llmservice -->|"resolves endpoints"| node_endpoints
node_llmservice -->|"dispatches requests"| node_providers
node_providers -->|"sends model requests"| node_modelservice
node_llmservice -->|"extracts model input"| node_extract
node_endpoints -->|"reads configuration"| node_preferences
node_notes -.->|"uses prompts"| node_prompts
node_researcher -->|"manages tasks"| node_mainwindow
node_researcher -->|"reads and asks"| node_pane

click node_startup "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/addon.ts"
click node_hooks "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/hooks.ts"
click node_taskqueue "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/taskQueue.ts"
click node_autoscan "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/autoScanManager.ts"
click node_extract "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/contentExtractor.ts"
click node_pdf "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/pdfExtractor.ts"
click node_notes "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/noteGenerator.ts"
click node_noteformat "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/noteMarkdown.ts"
click node_notestore "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/aiNoteService.ts"
click node_llmservice "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/llmService.ts"
click node_endpoints "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/llmEndpointManager.ts"
click node_providers "https://github.com/steven-jianhao-li/zotero-ai-butler/tree/main/src/modules/llmproviders"
click node_deepread "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/deepReadEngine.ts"
click node_review "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/literatureReviewService.ts"
click node_image "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/imageSummaryService.ts"
click node_mindmap "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/mindmapService.ts"
click node_pane "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/ItemPaneSection.ts"
click node_mainwindow "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/MainWindow.ts"
click node_summaryview "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/SummaryView.ts"
click node_reviewview "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/LiteratureReviewView.ts"
click node_preferences "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/utils/prefs.ts"
click node_prompts "https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/utils/prompts.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_startup,node_hooks toneBlue
class node_taskqueue,node_autoscan,node_extract,node_pdf,node_notes,node_noteformat,node_notestore toneAmber
class node_llmservice,node_endpoints,node_providers,node_modelservice toneMint
class node_deepread,node_review,node_image,node_mindmap toneRose
class node_pane,node_mainwindow,node_summaryview,node_reviewview,node_preferences,node_prompts,node_researcher,node_zotero toneIndigo
```

## Components

### Zotero entry

- [Plugin startup](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/addon.ts): `src/addon.ts`
- [Zotero hooks](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/hooks.ts): `src/hooks.ts`

### Paper workflow

- [Task queue](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/taskQueue.ts): `src/modules/taskQueue.ts`
- [Automatic scanning](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/autoScanManager.ts): `src/modules/autoScanManager.ts`
- [Content extraction](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/contentExtractor.ts): `src/modules/contentExtractor.ts`
- [PDF extraction](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/pdfExtractor.ts): `src/modules/pdfExtractor.ts`
- [Note generation](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/noteGenerator.ts): `src/modules/noteGenerator.ts`
- [Note formatting](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/noteMarkdown.ts): `src/modules/noteMarkdown.ts`
- [Zotero notes](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/aiNoteService.ts): `src/modules/aiNoteService.ts`

### Model services

- [LLM middleware](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/llmService.ts): `src/modules/llmService.ts`
- [Endpoint management](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/llmEndpointManager.ts): `src/modules/llmEndpointManager.ts`
- [Provider implementations](https://github.com/steven-jianhao-li/zotero-ai-butler/tree/main/src/modules/llmproviders): `src/modules/llmproviders`

### Research features

- [Deep reading](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/deepReadEngine.ts): `src/modules/deepReadEngine.ts`
- [Literature reviews](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/literatureReviewService.ts): `src/modules/literatureReviewService.ts`
- [Image summaries](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/imageSummaryService.ts): `src/modules/imageSummaryService.ts`
- [Mind maps](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/mindmapService.ts): `src/modules/mindmapService.ts`

### Plugin interface

- [Reader sidebar](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/ItemPaneSection.ts): `src/modules/ItemPaneSection.ts`
- [Main window](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/MainWindow.ts): `src/modules/views/MainWindow.ts`
- [Summary view](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/SummaryView.ts): `src/modules/views/SummaryView.ts`
- [Review view](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/modules/views/LiteratureReviewView.ts): `src/modules/views/LiteratureReviewView.ts`
- [Preferences](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/utils/prefs.ts): `src/utils/prefs.ts`
- [Prompt management](https://github.com/steven-jianhao-li/zotero-ai-butler/blob/main/src/utils/prompts.ts): `src/utils/prompts.ts`

### Other components

- **Researcher**
- **Zotero library**
- **Configured model API**

## Connections

- Researcher → Zotero library: adds papers
- Zotero library → Zotero hooks: triggers plugin (evidence: `src/hooks.ts`)
- Zotero hooks → Task queue: enqueues analysis (evidence: `src/hooks.ts`)
- Zotero hooks → Main window: opens dashboard (evidence: `src/hooks.ts`)
- Automatic scanning → Task queue: enqueues papers (evidence: `src/modules/autoScanManager.ts`)
- Task queue → Content extraction: requests content (evidence: `src/modules/taskQueue.ts`)
- Content extraction → PDF extraction: extracts PDFs (evidence: `src/modules/contentExtractor.ts`)
- Task queue → Note generation: runs summaries (evidence: `src/modules/taskQueue.ts`)
- Note generation → LLM middleware: requests generation
- Note generation → Note formatting: formats output
- Task queue → Image summaries: runs image summary (evidence: `src/modules/taskQueue.ts`)
- Task queue → Mind maps: runs mind maps (evidence: `src/modules/taskQueue.ts`)
- Task queue → Literature reviews: runs reviews (evidence: `src/modules/taskQueue.ts`)
- Review view → Literature reviews: configures reviews (evidence: `src/modules/views/LiteratureReviewView.ts`)
- Main window → Summary view: shows summary (evidence: `src/modules/views/MainWindow.ts`)
- Main window → Review view: shows reviews (evidence: `src/modules/views/MainWindow.ts`)
- Reader sidebar → Zotero notes: shows AI notes (evidence: `src/modules/ItemPaneSection.ts`)
- LLM middleware → Endpoint management: resolves endpoints (evidence: `src/modules/llmService.ts`)
- LLM middleware → Provider implementations: dispatches requests (evidence: `src/modules/llmService.ts`)
- Provider implementations → Configured model API: sends model requests
- LLM middleware → Content extraction: extracts model input (evidence: `src/modules/llmService.ts`)
- Endpoint management → Preferences: reads configuration (evidence: `src/modules/llmEndpointManager.ts`)
- Note generation → Prompt management: uses prompts
- Researcher → Main window: manages tasks
- Researcher → Reader sidebar: reads and asks
