# lightwindw/zotero-better-vertical-tabs architecture

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

- Interactive diagram: https://gitdiagram.com/lightwindw/zotero-better-vertical-tabs
- Repository: https://github.com/lightwindw/zotero-better-vertical-tabs

## Overview

Better Vertical Tabs is a Zotero plugin for organizing and managing open tabs in a vertical sidebar across the main window and PDF reader. Its runtime initializes tracking and category state, renders the sidebar, and responds to user actions such as searching, dragging, and saving categories. Tracking and category management keep the view synchronized with open tabs and persisted organization. The README also documents reader and idle-tab management, expand modes, preferences, and saved-category import. Some subsystem links reflect documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`src/modules/core/events.ts`](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/events.ts) (UI events), [`src/modules/track/categoryManager.ts`](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/categoryManager.ts) (Category manager), [`src/modules/core/lazyInit.ts`](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/lazyInit.ts) (Lazy initializer), [`src/modules/track/itemTracker.ts`](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/itemTracker.ts) (Open-tab tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Plugin Runtime"]
  node_entry["Plugin entry<br/>[index.ts]"]
  node_init["Lazy initializer<br/>[lazyInit.ts]"]
  node_events["UI events<br/>[events.ts]"]
end

subgraph group_sidebar["Sidebar Experience"]
  node_sidebarui["Vertical sidebar<br/>[sidebar.ts]"]
  node_renderer["Tab renderer<br/>[uiRenderer.ts]"]
  node_hover["Hover details<br/>[hoverCard.ts]"]
end

subgraph group_organize["Organization &amp; State"]
  node_categories["Category manager<br/>[categoryManager.ts]"]
  node_data[("Category state<br/>[dataStore.ts]")]
  node_saved[("Saved categories")]
  node_saveui["Save &amp; import UI"]
end

subgraph group_interaction["Drag &amp; Interaction"]
  node_drag["Tab drag &amp; drop"]
  node_externaldrag["External item drop"]
end

subgraph group_tracking["Tab &amp; Reader Tracking"]
  node_tracker["Open-tab tracker<br/>[itemTracker.ts]"]
  node_readers["Reader controls<br/>[readerRelease.ts]"]
  node_readeridle["Idle reader timer"]
  node_tabidle["Idle tab closing<br/>[autoClose.ts]"]
end

subgraph group_settings["Preferences"]
  node_prefs["Preferences UI"]
  node_prefstore["Preference utilities<br/>[prefs.ts]"]
end

node_user(("Zotero user"))
node_zotero["Zotero tabs &amp; readers"]

node_user -->|"uses"| node_sidebarui
node_entry -->|"starts"| node_init
node_init -->|"starts tracking"| node_tracker
node_init -->|"initializes"| node_categories
node_init -->|"shows"| node_sidebarui
node_init -->|"initializes"| node_hover
node_sidebarui -->|"dispatches"| node_events
node_renderer -->|"dispatches"| node_events
node_categories -->|"dispatches"| node_events
node_events -->|"notifies"| node_categories
node_events -->|"triggers render"| node_renderer
node_categories -->|"loads and saves"| node_data
node_categories -->|"loads and saves"| node_saved
node_renderer -->|"shows details"| node_hover
node_user -->|"searches &amp; selects"| node_renderer
node_user -->|"drags tabs"| node_drag
node_drag -->|"dispatches drop"| node_events
node_user -->|"drags items"| node_externaldrag
node_externaldrag -->|"previews drop"| node_events
node_zotero -->|"provides tab activity"| node_tracker
node_tracker -->|"updates open tabs"| node_categories
node_user -->|"opens or closes reader"| node_readers
node_readeridle -->|"closes idle readers"| node_readers
node_tracker -->|"tracks reading activity"| node_readeridle
node_tracker -->|"tracks tab activity"| node_tabidle
node_tabidle -->|"closes idle tabs"| node_zotero
node_user -->|"changes settings"| node_prefs
node_prefs -->|"reads and writes"| node_prefstore
node_prefs -->|"clears saved categories"| node_saved
node_prefs -->|"refreshes views"| node_events

click node_entry "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/index.ts"
click node_init "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/lazyInit.ts"
click node_events "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/events.ts"
click node_sidebarui "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/sidebar/sidebar.ts"
click node_renderer "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/render/uiRenderer.ts"
click node_hover "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/ui/hoverCard.ts"
click node_categories "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/categoryManager.ts"
click node_data "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/dataStore.ts"
click node_saved "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/save/savedCategoryStore.ts"
click node_saveui "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/save/saveCategoryDialog.ts"
click node_drag "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/drag/categoryDropAction.ts"
click node_externaldrag "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/drag/externalDropPreview.ts"
click node_tracker "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/itemTracker.ts"
click node_readers "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/readerRelease.ts"
click node_readeridle "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/readerReleaseTimer.ts"
click node_tabidle "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/autoClose.ts"
click node_prefs "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/preferenceScript.ts"
click node_prefstore "https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/utils/prefs.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_entry,node_init,node_events,node_user toneBlue
class node_sidebarui,node_renderer,node_hover toneAmber
class node_categories,node_data,node_saved,node_saveui toneMint
class node_drag,node_externaldrag toneRose
class node_tracker,node_readers,node_readeridle,node_tabidle,node_zotero toneIndigo
class node_prefs,node_prefstore toneTeal
```

## Components

### Plugin Runtime

- [Plugin entry](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/index.ts): `src/index.ts`
- [Lazy initializer](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/lazyInit.ts): `src/modules/core/lazyInit.ts`
- [UI events](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/core/events.ts): `src/modules/core/events.ts`

### Sidebar Experience

- [Vertical sidebar](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/sidebar/sidebar.ts): `src/modules/sidebar/sidebar.ts`
- [Tab renderer](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/render/uiRenderer.ts): `src/modules/render/uiRenderer.ts`
- [Hover details](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/ui/hoverCard.ts): `src/modules/ui/hoverCard.ts`

### Organization & State

- [Category manager](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/categoryManager.ts): `src/modules/track/categoryManager.ts`
- [Category state](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/dataStore.ts): `src/modules/track/dataStore.ts`
- [Saved categories](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/save/savedCategoryStore.ts): `src/modules/save/savedCategoryStore.ts`
- [Save & import UI](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/save/saveCategoryDialog.ts): `src/modules/save/saveCategoryDialog.ts`

### Drag & Interaction

- [Tab drag & drop](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/drag/categoryDropAction.ts): `src/modules/drag/categoryDropAction.ts`
- [External item drop](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/drag/externalDropPreview.ts): `src/modules/drag/externalDropPreview.ts`

### Tab & Reader Tracking

- [Open-tab tracker](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/itemTracker.ts): `src/modules/track/itemTracker.ts`
- [Reader controls](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/readerRelease.ts): `src/modules/track/readerRelease.ts`
- [Idle reader timer](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/readerReleaseTimer.ts): `src/modules/track/readerReleaseTimer.ts`
- [Idle tab closing](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/track/autoClose.ts): `src/modules/track/autoClose.ts`

### Preferences

- [Preferences UI](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/modules/preferenceScript.ts): `src/modules/preferenceScript.ts`
- [Preference utilities](https://github.com/lightwindw/zotero-better-vertical-tabs/blob/main/src/utils/prefs.ts): `src/utils/prefs.ts`

### Other components

- **Zotero user**
- **Zotero tabs & readers**

## Connections

- Zotero user → Vertical sidebar: uses
- Plugin entry → Lazy initializer: starts
- Lazy initializer → Open-tab tracker: starts tracking
- Lazy initializer → Category manager: initializes
- Lazy initializer → Vertical sidebar: shows
- Lazy initializer → Hover details: initializes
- Vertical sidebar → UI events: dispatches
- Tab renderer → UI events: dispatches
- Category manager → UI events: dispatches
- UI events → Category manager: notifies
- UI events → Tab renderer: triggers render
- Category manager → Category state: loads and saves
- Category manager → Saved categories: loads and saves
- Tab renderer → Hover details: shows details
- Zotero user → Tab renderer: searches & selects
- Zotero user → Tab drag & drop: drags tabs
- Tab drag & drop → UI events: dispatches drop
- Zotero user → External item drop: drags items
- External item drop → UI events: previews drop
- Zotero tabs & readers → Open-tab tracker: provides tab activity
- Open-tab tracker → Category manager: updates open tabs
- Zotero user → Reader controls: opens or closes reader
- Idle reader timer → Reader controls: closes idle readers
- Open-tab tracker → Idle reader timer: tracks reading activity
- Open-tab tracker → Idle tab closing: tracks tab activity
- Idle tab closing → Zotero tabs & readers: closes idle tabs
- Zotero user → Preferences UI: changes settings
- Preferences UI → Preference utilities: reads and writes
- Preferences UI → Saved categories: clears saved categories
- Preferences UI → UI events: refreshes views