# guaguastandup/zotero-pdf2zh architecture

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

- Interactive diagram: https://gitdiagram.com/guaguastandup/zotero-pdf2zh
- Repository: https://github.com/guaguastandup/zotero-pdf2zh

## Overview

Zotero PDF2zh is a Zotero add-on plus a local Python service for translating PDFs while preserving layout and supporting bilingual output, cropping, batch work, and configurable LLM services. The principal flow begins in Zotero, reaches the add-on’s translation worker and server, runs a translation task, and makes translated files available as attachments. The graph also includes configuration, environment management, and package updates. Some server and plugin implementations were not excerpted; those branches rely on README capabilities and source-index references rather than inspected call details.

Main entry points: [`server/server.py`](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/server.py) (HTTP service), [`plugin/src/modules/pdf2zhHelper.ts`](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhHelper.ts) (PDF worker), [`plugin/src/hooks.ts`](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/hooks.ts) (Lifecycle hooks), [`plugin/src/modules/pdf2zh.ts`](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zh.ts) (PDF actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_zotero["Zotero Add-on"]
  node_entry["Plugin entry<br/>[index.ts]"]
  node_lifecycle["Lifecycle hooks<br/>[hooks.ts]"]
  node_pdf_ui["PDF actions<br/>[pdf2zh.ts]"]
  node_worker["PDF worker<br/>[pdf2zhHelper.ts]"]
  node_file_processor["File processing"]
  node_attachments["Attachment handling"]
  node_preferences["Preferences UI"]
  node_llm_config["LLM configurations<br/>[llmApiManager.ts]"]
end

subgraph group_server["Translation Service"]
  node_server_api["HTTP service<br/>[server.py]"]
  node_task_manager["Task tracking<br/>[task_manager.py]"]
  node_config["Translation config<br/>[config.py]"]
  node_cropper["PDF cropping<br/>[cropper.py]"]
end

subgraph group_runtime["Translation Runtime"]
  node_executor["Engine execution<br/>[execute.py]"]
  node_pdf_engines["PDF2zh engines"]
end

subgraph group_maintenance["Environment and Updates"]
  node_environment["Managed environments"]
  node_venv["Environment detection<br/>[venv.py]"]
  node_package_network["Package sources<br/>[package_network.py]"]
  node_auto_update["Package updates<br/>[auto_update.py]"]
  node_update_command["Update command<br/>[update_packages.py]"]
end

node_user(("Zotero user"))
node_zotero_app(("Zotero"))
node_llm_services["LLM services"]

node_user -->|"starts PDF action"| node_pdf_ui
node_entry -->|"initializes"| node_lifecycle
node_lifecycle -->|"registers actions"| node_pdf_ui
node_lifecycle -->|"dispatches tasks"| node_worker
node_lifecycle -->|"loads preferences"| node_preferences
node_pdf_ui -.->|"adds Zotero UI"| node_zotero_app
node_worker -->|"uses"| node_file_processor
node_worker -->|"validates attachments"| node_attachments
node_worker -.->|"sends translation requests"| node_server_api
node_server_api -->|"tracks tasks"| node_task_manager
node_server_api -->|"loads configuration"| node_config
node_server_api -->|"uses crop operations"| node_cropper
node_server_api -->|"runs translation"| node_executor
node_executor -.->|"invokes engine"| node_pdf_engines
node_pdf_engines -.->|"uses configured services"| node_llm_services
node_server_api -->|"manages runtime"| node_environment
node_server_api -->|"detects environment"| node_venv
node_environment -->|"selects package sources"| node_package_network
node_server_api -->|"checks updates"| node_auto_update
node_update_command -->|"updates environment"| node_environment
node_preferences -->|"manages configurations"| node_llm_config
node_llm_config -->|"supplies active config"| node_worker
node_server_api -.->|"returns task results"| node_worker
node_worker -.->|"adds translated attachments"| node_zotero_app

click node_entry "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/index.ts"
click node_lifecycle "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/hooks.ts"
click node_pdf_ui "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zh.ts"
click node_worker "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhHelper.ts"
click node_file_processor "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhFileProcessor.ts"
click node_attachments "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhAttachmentUtils.ts"
click node_preferences "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/preferenceScript.ts"
click node_llm_config "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/llmApiManager.ts"
click node_server_api "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/server.py"
click node_task_manager "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/task_manager.py"
click node_config "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/config.py"
click node_cropper "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/cropper.py"
click node_executor "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/execute.py"
click node_environment "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/environment_lifecycle.py"
click node_venv "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/venv.py"
click node_package_network "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/package_network.py"
click node_auto_update "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/auto_update.py"
click node_update_command "https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/update_packages.py"

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_entry,node_lifecycle,node_pdf_ui,node_worker,node_file_processor,node_attachments,node_preferences,node_llm_config,node_user toneBlue
class node_server_api,node_task_manager,node_config,node_cropper toneAmber
class node_executor,node_pdf_engines toneMint
class node_environment,node_venv,node_package_network,node_auto_update,node_update_command toneRose
class node_zotero_app,node_llm_services toneIndigo
```

## Components

### Zotero Add-on

- [Plugin entry](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/index.ts): `plugin/src/index.ts`
- [Lifecycle hooks](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/hooks.ts): `plugin/src/hooks.ts`
- [PDF actions](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zh.ts): `plugin/src/modules/pdf2zh.ts`
- [PDF worker](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhHelper.ts): `plugin/src/modules/pdf2zhHelper.ts`
- [File processing](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhFileProcessor.ts): `plugin/src/modules/pdf2zhFileProcessor.ts`
- [Attachment handling](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/pdf2zhAttachmentUtils.ts): `plugin/src/modules/pdf2zhAttachmentUtils.ts`
- [Preferences UI](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/preferenceScript.ts): `plugin/src/modules/preferenceScript.ts`
- [LLM configurations](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/plugin/src/modules/llmApiManager.ts): `plugin/src/modules/llmApiManager.ts`

### Translation Service

- [HTTP service](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/server.py): `server/server.py`
- [Task tracking](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/task_manager.py): `server/utils/task_manager.py`
- [Translation config](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/config.py): `server/utils/config.py`
- [PDF cropping](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/cropper.py): `server/utils/cropper.py`

### Translation Runtime

- [Engine execution](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/execute.py): `server/utils/execute.py`
- **PDF2zh engines**

### Environment and Updates

- [Managed environments](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/environment_lifecycle.py): `server/utils/environment_lifecycle.py`
- [Environment detection](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/venv.py): `server/utils/venv.py`
- [Package sources](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/package_network.py): `server/utils/package_network.py`
- [Package updates](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/utils/auto_update.py): `server/utils/auto_update.py`
- [Update command](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server/update_packages.py): `server/update_packages.py`

### Other components

- **Zotero user**
- **Zotero**
- **LLM services**

## Connections

- Zotero user → PDF actions: starts PDF action
- Plugin entry → Lifecycle hooks: initializes (evidence: `plugin/src/index.ts`)
- Lifecycle hooks → PDF actions: registers actions (evidence: `plugin/src/hooks.ts`)
- Lifecycle hooks → PDF worker: dispatches tasks (evidence: `plugin/src/hooks.ts`)
- Lifecycle hooks → Preferences UI: loads preferences (evidence: `plugin/src/hooks.ts`)
- PDF actions → Zotero: adds Zotero UI
- PDF worker → File processing: uses (evidence: `plugin/src/modules/pdf2zhHelper.ts`)
- PDF worker → Attachment handling: validates attachments (evidence: `plugin/src/modules/pdf2zhHelper.ts`)
- PDF worker → HTTP service: sends translation requests
- HTTP service → Task tracking: tracks tasks (evidence: `server/server.py`)
- HTTP service → Translation config: loads configuration (evidence: `server/server.py`)
- HTTP service → PDF cropping: uses crop operations (evidence: `server/server.py`)
- HTTP service → Engine execution: runs translation (evidence: `server/server.py`)
- Engine execution → PDF2zh engines: invokes engine
- PDF2zh engines → LLM services: uses configured services
- HTTP service → Managed environments: manages runtime (evidence: `server/server.py`)
- HTTP service → Environment detection: detects environment (evidence: `server/server.py`)
- Managed environments → Package sources: selects package sources (evidence: `server/utils/environment_lifecycle.py`)
- HTTP service → Package updates: checks updates (evidence: `server/server.py`)
- Update command → Managed environments: updates environment (evidence: `server/update_packages.py`)
- Preferences UI → LLM configurations: manages configurations (evidence: `plugin/src/modules/preferenceScript.ts`)
- LLM configurations → PDF worker: supplies active config (evidence: `plugin/src/modules/pdf2zhHelper.ts`)
- HTTP service → PDF worker: returns task results
- PDF worker → Zotero: adds translated attachments
