# fdossi/zotread architecture

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

- Interactive diagram: https://gitdiagram.com/fdossi/zotread
- Repository: https://github.com/fdossi/zotread

## Overview

ZotRead is a Zotero 10 plugin for local reading-status indicators. Its main workflow combines automatic reader-open and annotation events with manual context-menu actions, persists state locally, aggregates annotation presence, and renders/sorts item-tree rows. The graph includes documented capabilities whose implementations were not sampled, such as manual actions and preferences; their links are limited to explicit README statements. Several runtime modules are unsampled, so uncertain internal wiring is omitted.

Main entry points: [`addon/content/zotread.js`](https://github.com/fdossi/zotread/blob/main/addon/content/zotread.js) (Runtime coordinator), [`addon/content/column.js`](https://github.com/fdossi/zotread/blob/main/addon/content/column.js) (Status column), [`addon/content/storage.js`](https://github.com/fdossi/zotread/blob/main/addon/content/storage.js) (State persistence), [`addon/content/notifier.js`](https://github.com/fdossi/zotread/blob/main/addon/content/notifier.js) (Library event observer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Plugin lifecycle"]
  node_bootstrap["Bootstrap<br/>[bootstrap.js]"]
  node_runtime["Runtime coordinator<br/>[zotread.js]"]
end

subgraph group_status["Reading status"]
  node_state["Status rules<br/>[state.js]"]
  node_storage["State persistence<br/>[storage.js]"]
  node_db[("Zotero database")]
  node_reader["Reader detection<br/>[reader.js]"]
  node_annotations["Annotation aggregation<br/>[annotations.js]"]
  node_notifier["Library event observer<br/>[notifier.js]"]
end

subgraph group_display["Indicators and controls"]
  node_column["Status column<br/>[column.js]"]
  node_menu["Manual actions<br/>[menu.js]"]
end

subgraph group_configuration["User configuration"]
  node_preferences["Settings pane<br/>[preferences.js]"]
  node_prefdefaults["Preference defaults<br/>[prefs.js]"]
end

node_zotero(("Zotero user"))
node_zotero_reader["Zotero reader"]
node_item_tree["Zotero item list"]
node_item_events["Zotero item events"]

node_zotero -.->|"opens attachment"| node_zotero_reader
node_zotero_reader -.->|"signals open"| node_reader
node_zotero -.->|"chooses actions"| node_menu
node_bootstrap -->|"starts"| node_runtime
node_runtime -->|"initializes"| node_storage
node_runtime -->|"initializes"| node_annotations
node_runtime -->|"initializes"| node_notifier
node_runtime -->|"registers"| node_column
node_runtime -->|"initializes"| node_reader
node_storage -->|"normalizes"| node_state
node_storage -->|"reads and writes"| node_db
node_column -->|"reads cached state"| node_storage
node_column -->|"checks presence"| node_annotations
node_column -->|"registers column"| node_item_tree
node_notifier -->|"resolves parents"| node_annotations
node_notifier -->|"applies annotation state"| node_runtime
node_notifier -->|"purges deleted state"| node_storage
node_notifier -->|"observes"| node_item_events
node_reader -.->|"marks opened items"| node_runtime
node_runtime -->|"stores status"| node_storage
node_runtime -->|"refreshes rows"| node_column
node_menu -.->|"sets status"| node_runtime
node_preferences -.->|"configures"| node_prefdefaults
node_preferences -.->|"repaints on color change"| node_column

click node_bootstrap "https://github.com/fdossi/zotread/blob/main/addon/bootstrap.js"
click node_runtime "https://github.com/fdossi/zotread/blob/main/addon/content/zotread.js"
click node_state "https://github.com/fdossi/zotread/blob/main/addon/content/state.js"
click node_storage "https://github.com/fdossi/zotread/blob/main/addon/content/storage.js"
click node_reader "https://github.com/fdossi/zotread/blob/main/addon/content/reader.js"
click node_annotations "https://github.com/fdossi/zotread/blob/main/addon/content/annotations.js"
click node_notifier "https://github.com/fdossi/zotread/blob/main/addon/content/notifier.js"
click node_column "https://github.com/fdossi/zotread/blob/main/addon/content/column.js"
click node_menu "https://github.com/fdossi/zotread/blob/main/addon/content/menu.js"
click node_preferences "https://github.com/fdossi/zotread/blob/main/addon/content/preferences.js"
click node_prefdefaults "https://github.com/fdossi/zotread/blob/main/addon/prefs.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_runtime,node_zotero toneBlue
class node_state,node_storage,node_db,node_reader,node_annotations,node_notifier toneAmber
class node_column,node_menu toneMint
class node_preferences,node_prefdefaults toneRose
class node_zotero_reader,node_item_tree,node_item_events toneIndigo
```

## Components

### Plugin lifecycle

- [Bootstrap](https://github.com/fdossi/zotread/blob/main/addon/bootstrap.js): `addon/bootstrap.js`
- [Runtime coordinator](https://github.com/fdossi/zotread/blob/main/addon/content/zotread.js): `addon/content/zotread.js`

### Reading status

- [Status rules](https://github.com/fdossi/zotread/blob/main/addon/content/state.js): `addon/content/state.js`
- [State persistence](https://github.com/fdossi/zotread/blob/main/addon/content/storage.js): `addon/content/storage.js`
- **Zotero database**
- [Reader detection](https://github.com/fdossi/zotread/blob/main/addon/content/reader.js): `addon/content/reader.js`
- [Annotation aggregation](https://github.com/fdossi/zotread/blob/main/addon/content/annotations.js): `addon/content/annotations.js`
- [Library event observer](https://github.com/fdossi/zotread/blob/main/addon/content/notifier.js): `addon/content/notifier.js`

### Indicators and controls

- [Status column](https://github.com/fdossi/zotread/blob/main/addon/content/column.js): `addon/content/column.js`
- [Manual actions](https://github.com/fdossi/zotread/blob/main/addon/content/menu.js): `addon/content/menu.js`

### User configuration

- [Settings pane](https://github.com/fdossi/zotread/blob/main/addon/content/preferences.js): `addon/content/preferences.js`
- [Preference defaults](https://github.com/fdossi/zotread/blob/main/addon/prefs.js): `addon/prefs.js`

### Other components

- **Zotero user**
- **Zotero reader**
- **Zotero item list**
- **Zotero item events**

## Connections

- Zotero user → Zotero reader: opens attachment (evidence: `README.md`)
- Zotero reader → Reader detection: signals open (evidence: `README.md`)
- Zotero user → Manual actions: chooses actions (evidence: `README.md`)
- Bootstrap → Runtime coordinator: starts (evidence: `addon/bootstrap.js`)
- Runtime coordinator → State persistence: initializes (evidence: `addon/content/zotread.js`)
- Runtime coordinator → Annotation aggregation: initializes (evidence: `addon/content/zotread.js`)
- Runtime coordinator → Library event observer: initializes (evidence: `addon/content/zotread.js`)
- Runtime coordinator → Status column: registers (evidence: `addon/content/zotread.js`)
- Runtime coordinator → Reader detection: initializes (evidence: `addon/content/zotread.js`)
- State persistence → Status rules: normalizes (evidence: `addon/content/storage.js`)
- State persistence → Zotero database: reads and writes (evidence: `addon/content/storage.js`)
- Status column → State persistence: reads cached state (evidence: `addon/content/column.js`)
- Status column → Annotation aggregation: checks presence (evidence: `addon/content/column.js`)
- Status column → Zotero item list: registers column (evidence: `addon/content/column.js`)
- Library event observer → Annotation aggregation: resolves parents (evidence: `addon/content/notifier.js`)
- Library event observer → Runtime coordinator: applies annotation state (evidence: `addon/content/notifier.js`)
- Library event observer → State persistence: purges deleted state (evidence: `addon/content/notifier.js`)
- Library event observer → Zotero item events: observes (evidence: `addon/content/notifier.js`)
- Reader detection → Runtime coordinator: marks opened items
- Runtime coordinator → State persistence: stores status (evidence: `addon/content/zotread.js`)
- Runtime coordinator → Status column: refreshes rows (evidence: `addon/content/zotread.js`)
- Manual actions → Runtime coordinator: sets status (evidence: `README.md`)
- Settings pane → Preference defaults: configures (evidence: `README.md`)
- Settings pane → Status column: repaints on color change (evidence: `README.md`)