# peterdresslar/zotero-gemini-notebook architecture

> Architecture diagram of the GitHub repository peterdresslar/zotero-gemini-notebook, 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/peterdresslar/zotero-gemini-notebook
- Repository: https://github.com/peterdresslar/zotero-gemini-notebook

## Overview

Zotero Gemini Notebook stages selected Zotero attachments, serves only staged files over a local bridge, and uses a Chrome extension to hand them to Gemini Notebook. The optional MCP interface can stage jobs and report their status; it does not perform the browser upload. The graph preserves the documented browse, upload, Studio-prompt, and MCP-configuration capabilities. Some extension internals are unsampled, so only documented high-level links are shown for them.

Main entry points: [`src/modules/server.ts`](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/server.ts) (Zotero HTTP bridge), [`src/modules/dialog.ts`](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/dialog.ts) (Collection browser), [`src/modules/stagingAction.ts`](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/stagingAction.ts) (Quick staging action), [`chrome-extension/popup.js`](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/popup.js) (Import popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_zotero["Zotero plugin"]
  node_dialog["Collection browser<br/>[dialog.ts]"]
  node_collections["Collection access<br/>[collections.ts]"]
  node_items["Item discovery<br/>[items.ts]"]
  node_quickstage["Quick staging action<br/>[stagingAction.ts]"]
end

subgraph group_bridge["Local bridge"]
  node_staging["Human staging<br/>[staging.ts]"]
  node_jobstore[("Bridge job store<br/>[bridgeJobStore.js]")]
  node_localserver["Zotero HTTP bridge<br/>[server.ts]"]
  node_jobapi["Agent job API<br/>[bridgeJobs.ts]"]
  node_eventserver["Chrome job events"]
end

subgraph group_chrome["Chrome handoff"]
  node_extension["Chrome extension<br/>[background.js]"]
  node_popup["Import popup<br/>[popup.js]"]
  node_requests["Bridge requests<br/>[bridge-requests.js]"]
  node_handoff["Upload handoff<br/>[upload-handoff.js]"]
  node_injector["Page injector<br/>[injector.js]"]
  node_lifecycle["Upload lifecycle<br/>[job-lifecycle.js]"]
end

subgraph group_mcp["MCP interface"]
  node_mcpserver["MCP stdio adapter<br/>[server.py]"]
  node_mcpjobs["MCP job tools<br/>[zotero_jobs.py]"]
  node_mcpstatus["MCP status tool<br/>[zotero_status.py]"]
  node_control["MCP control server"]
  node_auth["Local authorization<br/>[mcpLocalAuth.ts]"]
  node_configdialog["MCP setup dialog<br/>[mcpConfigDialog.ts]"]
  node_autoconfig["Client auto-config"]
end

subgraph group_destination["External services"]
  node_gemini(("Gemini Notebook"))
  node_mcpclient(("AI client"))
end

node_user(("Zotero user"))

node_user -->|"browses sources"| node_dialog
node_dialog -->|"loads collections"| node_collections
node_dialog -->|"finds items"| node_items
node_dialog -->|"stages selection"| node_quickstage
node_user -->|"exports selection"| node_quickstage
node_quickstage -->|"resolves attachments"| node_items
node_quickstage -->|"stages files"| node_staging
node_staging -->|"activates job"| node_jobstore
node_localserver -->|"reads staged state"| node_staging
node_localserver -->|"claims staged job"| node_jobstore
node_localserver -->|"serves staged files"| node_extension
node_extension -.->|"opens import UI"| node_popup
node_popup -->|"requests bridge data"| node_requests
node_popup -->|"starts handoff"| node_handoff
node_handoff -.->|"coordinates page upload"| node_injector
node_injector -->|"uploads sources"| node_gemini
node_lifecycle -.->|"reports job events"| node_eventserver
node_mcpclient -->|"calls MCP tools"| node_mcpserver
node_mcpserver -->|"registers job tools"| node_mcpjobs
node_mcpserver -->|"registers status tool"| node_mcpstatus
node_mcpjobs -->|"sends authenticated requests"| node_localserver
node_mcpstatus -->|"checks bridge status"| node_localserver
node_control -->|"creates and reads jobs"| node_jobapi
node_jobapi -->|"stores agent jobs"| node_jobstore
node_control -->|"checks local authorization"| node_auth
node_user -->|"configures MCP"| node_configdialog
node_configdialog -->|"plans client setup"| node_autoconfig
node_autoconfig -.->|"configures launch"| node_mcpclient

click node_dialog "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/dialog.ts"
click node_collections "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/collections.ts"
click node_items "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/items.ts"
click node_quickstage "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/stagingAction.ts"
click node_staging "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/staging.ts"
click node_jobstore "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/bridgeJobStore.js"
click node_localserver "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/server.ts"
click node_jobapi "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/bridgeJobs.ts"
click node_eventserver "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/chromeJobEventServer.ts"
click node_extension "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/background.js"
click node_popup "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/popup.js"
click node_requests "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/bridge-requests.js"
click node_handoff "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/upload-handoff.js"
click node_injector "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/injector.js"
click node_lifecycle "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/job-lifecycle.js"
click node_mcpserver "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/server.py"
click node_mcpjobs "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/zotero_jobs.py"
click node_mcpstatus "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/zotero_status.py"
click node_control "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpControlServer.ts"
click node_auth "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpLocalAuth.ts"
click node_configdialog "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpConfigDialog.ts"
click node_autoconfig "https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpClientAutoConfig.js"

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_dialog,node_collections,node_items,node_quickstage,node_user toneBlue
class node_staging,node_jobstore,node_localserver,node_jobapi,node_eventserver toneAmber
class node_extension,node_popup,node_requests,node_handoff,node_injector,node_lifecycle toneMint
class node_mcpserver,node_mcpjobs,node_mcpstatus,node_control,node_auth,node_configdialog,node_autoconfig toneRose
class node_gemini,node_mcpclient toneIndigo
```

## Components

### Zotero plugin

- [Collection browser](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/dialog.ts): `src/modules/dialog.ts`
- [Collection access](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/collections.ts): `src/modules/collections.ts`
- [Item discovery](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/items.ts): `src/modules/items.ts`
- [Quick staging action](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/stagingAction.ts): `src/modules/stagingAction.ts`

### Local bridge

- [Human staging](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/staging.ts): `src/modules/staging.ts`
- [Bridge job store](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/bridgeJobStore.js): `src/modules/bridgeJobStore.js`
- [Zotero HTTP bridge](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/server.ts): `src/modules/server.ts`
- [Agent job API](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/bridgeJobs.ts): `src/modules/bridgeJobs.ts`
- [Chrome job events](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/chromeJobEventServer.ts): `src/modules/chromeJobEventServer.ts`

### Chrome handoff

- [Chrome extension](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/background.js): `chrome-extension/background.js`
- [Import popup](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/popup.js): `chrome-extension/popup.js`
- [Bridge requests](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/bridge-requests.js): `chrome-extension/bridge-requests.js`
- [Upload handoff](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/upload-handoff.js): `chrome-extension/upload-handoff.js`
- [Page injector](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/injector.js): `chrome-extension/injector.js`
- [Upload lifecycle](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/chrome-extension/job-lifecycle.js): `chrome-extension/job-lifecycle.js`

### MCP interface

- [MCP stdio adapter](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/server.py): `mcp-adapter/server.py`
- [MCP job tools](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/zotero_jobs.py): `mcp-adapter/zotero_jobs.py`
- [MCP status tool](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/mcp-adapter/zotero_status.py): `mcp-adapter/zotero_status.py`
- [MCP control server](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpControlServer.ts): `src/modules/mcpControlServer.ts`
- [Local authorization](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpLocalAuth.ts): `src/modules/mcpLocalAuth.ts`
- [MCP setup dialog](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpConfigDialog.ts): `src/modules/mcpConfigDialog.ts`
- [Client auto-config](https://github.com/peterdresslar/zotero-gemini-notebook/blob/main/src/modules/mcpClientAutoConfig.js): `src/modules/mcpClientAutoConfig.js`

### External services

- **Gemini Notebook**
- **AI client**

### Other components

- **Zotero user**

## Connections

- Zotero user → Collection browser: browses sources
- Collection browser → Collection access: loads collections (evidence: `src/modules/dialog.ts`)
- Collection browser → Item discovery: finds items (evidence: `src/modules/dialog.ts`)
- Collection browser → Quick staging action: stages selection (evidence: `src/modules/dialog.ts`)
- Zotero user → Quick staging action: exports selection
- Quick staging action → Item discovery: resolves attachments (evidence: `src/modules/stagingAction.ts`)
- Quick staging action → Human staging: stages files (evidence: `src/modules/stagingAction.ts`)
- Human staging → Bridge job store: activates job (evidence: `src/modules/staging.ts`)
- Zotero HTTP bridge → Human staging: reads staged state (evidence: `src/modules/server.ts`)
- Zotero HTTP bridge → Bridge job store: claims staged job (evidence: `src/modules/server.ts`)
- Zotero HTTP bridge → Chrome extension: serves staged files
- Chrome extension → Import popup: opens import UI
- Import popup → Bridge requests: requests bridge data (evidence: `chrome-extension/popup.js`)
- Import popup → Upload handoff: starts handoff (evidence: `chrome-extension/popup.js`)
- Upload handoff → Page injector: coordinates page upload
- Page injector → Gemini Notebook: uploads sources
- Upload lifecycle → Chrome job events: reports job events
- AI client → MCP stdio adapter: calls MCP tools
- MCP stdio adapter → MCP job tools: registers job tools (evidence: `mcp-adapter/server.py`)
- MCP stdio adapter → MCP status tool: registers status tool (evidence: `mcp-adapter/server.py`)
- MCP job tools → Zotero HTTP bridge: sends authenticated requests
- MCP status tool → Zotero HTTP bridge: checks bridge status
- MCP control server → Agent job API: creates and reads jobs (evidence: `src/modules/mcpControlServer.ts`)
- Agent job API → Bridge job store: stores agent jobs (evidence: `src/modules/bridgeJobs.ts`)
- MCP control server → Local authorization: checks local authorization (evidence: `src/modules/mcpControlServer.ts`)
- Zotero user → MCP setup dialog: configures MCP
- MCP setup dialog → Client auto-config: plans client setup (evidence: `src/modules/mcpConfigDialog.ts`)
- Client auto-config → AI client: configures launch
