# aaronkhodami/zotgit architecture

> Architecture diagram of the GitHub repository aaronkhodami/zotgit, 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/aaronkhodami/zotgit
- Repository: https://github.com/aaronkhodami/zotgit

## Overview

ZotGit is a Zotero extension for managing attachment files and syncing settings and PDFs with GitHub. Its main workflow is to move or copy imported attachments into a configured directory and link them to Zotero items; users can also manage attachments from context menus. Sync is an optional branch with scheduled/manual pushes, startup pulls, and remote-PDF recall. The README documents several capabilities whose internal call paths are not shown, so those relationships are cited to the README; source-level edges use the shown bootstrap wiring.

Main entry points: [`bootstrap.js`](https://github.com/aaronkhodami/zotgit/blob/main/bootstrap.js) (Extension startup), [`src/06-zotmoov-sync.js`](https://github.com/aaronkhodami/zotgit/blob/main/src/06-zotmoov-sync.js) (Sync coordinator), [`src/02-zotmoov.js`](https://github.com/aaronkhodami/zotgit/blob/main/src/02-zotmoov.js) (Attachment handling), [`src/03-zotmoov-menus.js`](https://github.com/aaronkhodami/zotgit/blob/main/src/03-zotmoov-menus.js) (Context menus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_bootstrap["Extension startup<br/>[bootstrap.js]"]
  node_patcher["Zotero patching"]
  node_sanitizer["Filename sanitizer"]
end

subgraph group_attachments["Attachment management"]
  node_core["Attachment handling<br/>[02-zotmoov.js]"]
  node_wildcards["Wildcard rules"]
  node_parser["Wildcard commands"]
  node_deletequeue["Delete queue"]
  node_notify["Attachment callbacks"]
  node_localfiles[("Attachment directory")]
end

subgraph group_configuration["Settings and menus"]
  node_menus["Context menus"]
  node_custommenus["Custom menu items"]
  node_bindings["Window bindings"]
  node_prefs["General preferences<br/>[zotmoov-prefs.js]"]
  node_advancedprefs["Advanced preferences"]
end

subgraph group_sync["GitHub sync"]
  node_sync["Sync coordinator<br/>[06-zotmoov-sync.js]"]
  node_cache[("Temporary PDF cache")]
  node_github[("GitHub repository")]
end

subgraph group_logging["Logging"]
  node_directorymanager["Log directory"]
  node_debugger["Extension debugger"]
  node_outputmanager["Log output"]
end

node_user(("Zotero user"))
node_zotero[("Zotero library")]

node_user -->|"configures"| node_prefs
node_user -->|"manages attachments"| node_menus
node_zotero -->|"imports attachments"| node_core
node_core -->|"moves or copies"| node_localfiles
node_core -->|"links attachments"| node_zotero
node_menus -->|"requests move or copy"| node_core
node_zotero -->|"deletion queues unlink"| node_deletequeue
node_user -->|"attaches latest file"| node_notify
node_bootstrap -->|"constructs"| node_core
node_bootstrap -->|"constructs"| node_bindings
node_bootstrap -->|"constructs"| node_menus
node_bootstrap -->|"constructs"| node_sync
node_bootstrap -->|"constructs"| node_wildcards
node_bootstrap -->|"constructs"| node_sanitizer
node_bootstrap -->|"creates"| node_directorymanager
node_bootstrap -->|"creates"| node_debugger
node_bootstrap -->|"loads scripts"| node_custommenus
node_bootstrap -->|"loads scripts"| node_patcher
node_bootstrap -->|"loads scripts"| node_parser
node_bootstrap -->|"loads scripts"| node_notify
node_wildcards -.->|"uses commands"| node_parser
node_prefs -->|"checks auth"| node_sync
node_advancedprefs -->|"pushes settings"| node_sync
node_sync -->|"pushes and pulls"| node_github
node_sync -->|"recalls remote PDFs"| node_cache
node_sync -->|"syncs PDFs"| node_localfiles
node_debugger -->|"writes logs"| node_outputmanager
node_outputmanager -->|"gets log file"| node_directorymanager

click node_bootstrap "https://github.com/aaronkhodami/zotgit/blob/main/bootstrap.js"
click node_core "https://github.com/aaronkhodami/zotgit/blob/main/src/02-zotmoov.js"
click node_wildcards "https://github.com/aaronkhodami/zotgit/blob/main/src/00-zotmoov-wildcard.js"
click node_parser "https://github.com/aaronkhodami/zotgit/blob/main/src/00-zotmoov-command-parser.js"
click node_deletequeue "https://github.com/aaronkhodami/zotgit/blob/main/src/01-zotmoov-delete-queue.js"
click node_notify "https://github.com/aaronkhodami/zotgit/blob/main/src/01-zotmoov-notify-callback.js"
click node_menus "https://github.com/aaronkhodami/zotgit/blob/main/src/03-zotmoov-menus.js"
click node_custommenus "https://github.com/aaronkhodami/zotgit/blob/main/src/03-zotmoov-custom-menus.js"
click node_bindings "https://github.com/aaronkhodami/zotgit/blob/main/src/05-zotmoov-bindings.js"
click node_prefs "https://github.com/aaronkhodami/zotgit/blob/main/preferences/zotmoov-prefs.js"
click node_advancedprefs "https://github.com/aaronkhodami/zotgit/blob/main/preferences/zotmoov-adv-prefs.js"
click node_patcher "https://github.com/aaronkhodami/zotgit/blob/main/src/04-zotmoov-patcher.js"
click node_sync "https://github.com/aaronkhodami/zotgit/blob/main/src/06-zotmoov-sync.js"
click node_directorymanager "https://github.com/aaronkhodami/zotgit/blob/main/lib/logging/00-directory-manager.js"
click node_debugger "https://github.com/aaronkhodami/zotgit/blob/main/lib/00-zotmoov-debugger.js"
click node_outputmanager "https://github.com/aaronkhodami/zotgit/blob/main/lib/logging/04-output-manager.js"
click node_sanitizer "https://github.com/aaronkhodami/zotgit/blob/main/lib/02-sanitize-filename.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_bootstrap,node_patcher,node_sanitizer,node_user toneBlue
class node_core,node_wildcards,node_parser,node_deletequeue,node_notify,node_localfiles,node_zotero toneAmber
class node_menus,node_custommenus,node_bindings,node_prefs,node_advancedprefs toneMint
class node_sync,node_cache,node_github toneRose
class node_directorymanager,node_debugger,node_outputmanager toneIndigo
```

## Components

### Extension runtime

- [Extension startup](https://github.com/aaronkhodami/zotgit/blob/main/bootstrap.js): `bootstrap.js`
- [Zotero patching](https://github.com/aaronkhodami/zotgit/blob/main/src/04-zotmoov-patcher.js): `src/04-zotmoov-patcher.js`
- [Filename sanitizer](https://github.com/aaronkhodami/zotgit/blob/main/lib/02-sanitize-filename.js): `lib/02-sanitize-filename.js`

### Attachment management

- [Attachment handling](https://github.com/aaronkhodami/zotgit/blob/main/src/02-zotmoov.js): `src/02-zotmoov.js`
- [Wildcard rules](https://github.com/aaronkhodami/zotgit/blob/main/src/00-zotmoov-wildcard.js): `src/00-zotmoov-wildcard.js`
- [Wildcard commands](https://github.com/aaronkhodami/zotgit/blob/main/src/00-zotmoov-command-parser.js): `src/00-zotmoov-command-parser.js`
- [Delete queue](https://github.com/aaronkhodami/zotgit/blob/main/src/01-zotmoov-delete-queue.js): `src/01-zotmoov-delete-queue.js`
- [Attachment callbacks](https://github.com/aaronkhodami/zotgit/blob/main/src/01-zotmoov-notify-callback.js): `src/01-zotmoov-notify-callback.js`
- **Attachment directory**

### Settings and menus

- [Context menus](https://github.com/aaronkhodami/zotgit/blob/main/src/03-zotmoov-menus.js): `src/03-zotmoov-menus.js`
- [Custom menu items](https://github.com/aaronkhodami/zotgit/blob/main/src/03-zotmoov-custom-menus.js): `src/03-zotmoov-custom-menus.js`
- [Window bindings](https://github.com/aaronkhodami/zotgit/blob/main/src/05-zotmoov-bindings.js): `src/05-zotmoov-bindings.js`
- [General preferences](https://github.com/aaronkhodami/zotgit/blob/main/preferences/zotmoov-prefs.js): `preferences/zotmoov-prefs.js`
- [Advanced preferences](https://github.com/aaronkhodami/zotgit/blob/main/preferences/zotmoov-adv-prefs.js): `preferences/zotmoov-adv-prefs.js`

### GitHub sync

- [Sync coordinator](https://github.com/aaronkhodami/zotgit/blob/main/src/06-zotmoov-sync.js): `src/06-zotmoov-sync.js`
- **Temporary PDF cache**
- **GitHub repository**

### Logging

- [Log directory](https://github.com/aaronkhodami/zotgit/blob/main/lib/logging/00-directory-manager.js): `lib/logging/00-directory-manager.js`
- [Extension debugger](https://github.com/aaronkhodami/zotgit/blob/main/lib/00-zotmoov-debugger.js): `lib/00-zotmoov-debugger.js`
- [Log output](https://github.com/aaronkhodami/zotgit/blob/main/lib/logging/04-output-manager.js): `lib/logging/04-output-manager.js`

### Other components

- **Zotero user**
- **Zotero library**

## Connections

- Zotero user → General preferences: configures (evidence: `README.md`)
- Zotero user → Context menus: manages attachments (evidence: `README.md`)
- Zotero library → Attachment handling: imports attachments (evidence: `README.md`)
- Attachment handling → Attachment directory: moves or copies (evidence: `README.md`)
- Attachment handling → Zotero library: links attachments (evidence: `README.md`)
- Context menus → Attachment handling: requests move or copy (evidence: `README.md`)
- Zotero library → Delete queue: deletion queues unlink (evidence: `README.md`)
- Zotero user → Attachment callbacks: attaches latest file (evidence: `README.md`)
- Extension startup → Attachment handling: constructs (evidence: `bootstrap.js`)
- Extension startup → Window bindings: constructs (evidence: `bootstrap.js`)
- Extension startup → Context menus: constructs (evidence: `bootstrap.js`)
- Extension startup → Sync coordinator: constructs (evidence: `bootstrap.js`)
- Extension startup → Wildcard rules: constructs (evidence: `bootstrap.js`)
- Extension startup → Filename sanitizer: constructs (evidence: `bootstrap.js`)
- Extension startup → Log directory: creates (evidence: `bootstrap.js`)
- Extension startup → Extension debugger: creates (evidence: `bootstrap.js`)
- Extension startup → Custom menu items: loads scripts (evidence: `bootstrap.js`)
- Extension startup → Zotero patching: loads scripts (evidence: `bootstrap.js`)
- Extension startup → Wildcard commands: loads scripts (evidence: `bootstrap.js`)
- Extension startup → Attachment callbacks: loads scripts (evidence: `bootstrap.js`)
- Wildcard rules → Wildcard commands: uses commands
- General preferences → Sync coordinator: checks auth (evidence: `preferences/zotmoov-prefs.js`)
- Advanced preferences → Sync coordinator: pushes settings (evidence: `preferences/zotmoov-adv-prefs.js`)
- Sync coordinator → GitHub repository: pushes and pulls (evidence: `README.md`)
- Sync coordinator → Temporary PDF cache: recalls remote PDFs (evidence: `README.md`)
- Sync coordinator → Attachment directory: syncs PDFs (evidence: `README.md`)
- Extension debugger → Log output: writes logs (evidence: `lib/00-zotmoov-debugger.js`)
- Log output → Log directory: gets log file (evidence: `lib/logging/04-output-manager.js`)