# tidedra/zotero-arxiv-daily architecture

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

- Interactive diagram: https://gitdiagram.com/tidedra/zotero-arxiv-daily
- Repository: https://github.com/tidedra/zotero-arxiv-daily

## Overview

Zotero-arXiv-Daily fetches a user’s Zotero library and recent preprints, ranks candidates against the library, enriches selected papers, then emails a daily digest. The README documents four sources, local or API-based reranking, LLM summaries and affiliations, and PDF/code links. The graph follows the executor as the orchestrator; some feature links are documented in the README but their implementation was not sampled.

Main entry points: [`src/zotero_arxiv_daily/executor.py`](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/executor.py) (Workflow executor), [`src/zotero_arxiv_daily/retriever/base.py`](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/base.py) (Retriever framework), [`src/zotero_arxiv_daily/retriever/arxiv_retriever.py`](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/arxiv_retriever.py) (arXiv retrieval), [`src/zotero_arxiv_daily/reranker/base.py`](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/base.py) (Relevance scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow and delivery"]
  node_entry["Application entry<br/>[main.py]"]
  node_executor["Workflow executor<br/>[executor.py]"]
  node_email["Digest rendering<br/>[construct_email.py]"]
  node_mail["SMTP delivery<br/>[utils.py]"]
  node_config["Runtime configuration<br/>[default.yaml]"]
end

subgraph group_library["Zotero interest model"]
  node_zotero[("Zotero library")]
  node_corpus["Library corpus<br/>[protocol.py]"]
  node_filter["Collection filtering<br/>[executor.py]"]
end

subgraph group_sources["Preprint sources"]
  node_arxiv["arXiv retrieval<br/>[arxiv_retriever.py]"]
  node_biorxiv["bioRxiv retrieval"]
  node_medrxiv["medRxiv retrieval"]
  node_chemrxiv["chemRxiv retrieval"]
  node_retrieverbase["Retriever framework<br/>[base.py]"]
end

subgraph group_ranking["Relevance ranking"]
  node_rankbase["Relevance scoring<br/>[base.py]"]
  node_localrank["Local embeddings<br/>[local.py]"]
  node_apirank["Embedding API<br/>[api.py]"]
end

subgraph group_enrichment["Paper enrichment"]
  node_papers["Paper records<br/>[protocol.py]"]
  node_llm["LLM enrichment<br/>[protocol.py]"]
  node_paperutils["PDF and TeX extraction<br/>[utils.py]"]
end

node_schedule(("Scheduled run"))
node_recipient(("Mailbox recipient"))
node_llmservice["LLM service"]
node_sourceservice["Preprint services"]
node_embeddingservice["Embedding service"]

node_schedule -.->|"starts"| node_entry
node_entry -->|"runs"| node_executor
node_config -.->|"configures"| node_executor
node_executor -->|"fetches library"| node_zotero
node_executor -->|"filters corpus"| node_filter
node_executor -->|"builds corpus"| node_corpus
node_executor -->|"selects retrievers"| node_retrieverbase
node_retrieverbase -->|"registers"| node_arxiv
node_retrieverbase -->|"registers"| node_biorxiv
node_retrieverbase -->|"registers"| node_medrxiv
node_retrieverbase -->|"registers"| node_chemrxiv
node_arxiv -->|"queries"| node_sourceservice
node_biorxiv -->|"queries"| node_sourceservice
node_chemrxiv -->|"queries Crossref"| node_sourceservice
node_executor -->|"reranks papers"| node_rankbase
node_rankbase -->|"uses scorer"| node_localrank
node_rankbase -->|"uses scorer"| node_apirank
node_apirank -->|"requests embeddings"| node_embeddingservice
node_executor -->|"enriches selected papers"| node_llm
node_llm -->|"requests summaries and affiliations"| node_llmservice
node_arxiv -->|"extracts text"| node_paperutils
node_executor -->|"renders digest"| node_email
node_executor -->|"sends digest"| node_mail
node_mail -->|"delivers email"| node_recipient
node_email -.->|"formats paper details"| node_papers
node_papers -.->|"provides PDF and code links"| node_recipient

click node_entry "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/main.py"
click node_executor "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/executor.py"
click node_email "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/construct_email.py"
click node_mail "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/utils.py"
click node_config "https://github.com/tidedra/zotero-arxiv-daily/blob/main/config/default.yaml"
click node_corpus "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py"
click node_filter "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/executor.py"
click node_arxiv "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/arxiv_retriever.py"
click node_biorxiv "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/biorxiv_retriever.py"
click node_medrxiv "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/medrxiv_retriever.py"
click node_chemrxiv "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/chemrxiv_retriever.py"
click node_retrieverbase "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/base.py"
click node_papers "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py"
click node_rankbase "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/base.py"
click node_localrank "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/local.py"
click node_apirank "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/api.py"
click node_llm "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py"
click node_paperutils "https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/utils.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_executor,node_email,node_mail,node_config toneBlue
class node_zotero,node_corpus,node_filter toneAmber
class node_arxiv,node_biorxiv,node_medrxiv,node_chemrxiv,node_retrieverbase toneMint
class node_rankbase,node_localrank,node_apirank toneRose
class node_papers,node_llm,node_paperutils,node_schedule,node_recipient,node_llmservice,node_sourceservice,node_embeddingservice toneIndigo
```

## Components

### Workflow and delivery

- [Application entry](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/main.py): `src/zotero_arxiv_daily/main.py`
- [Workflow executor](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/executor.py): `src/zotero_arxiv_daily/executor.py`
- [Digest rendering](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/construct_email.py): `src/zotero_arxiv_daily/construct_email.py`
- [SMTP delivery](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/utils.py): `src/zotero_arxiv_daily/utils.py`
- [Runtime configuration](https://github.com/tidedra/zotero-arxiv-daily/blob/main/config/default.yaml): `config/default.yaml`

### Zotero interest model

- **Zotero library**
- [Library corpus](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py): `src/zotero_arxiv_daily/protocol.py`
- [Collection filtering](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/executor.py): `src/zotero_arxiv_daily/executor.py`

### Preprint sources

- [arXiv retrieval](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/arxiv_retriever.py): `src/zotero_arxiv_daily/retriever/arxiv_retriever.py`
- [bioRxiv retrieval](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/biorxiv_retriever.py): `src/zotero_arxiv_daily/retriever/biorxiv_retriever.py`
- [medRxiv retrieval](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/medrxiv_retriever.py): `src/zotero_arxiv_daily/retriever/medrxiv_retriever.py`
- [chemRxiv retrieval](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/chemrxiv_retriever.py): `src/zotero_arxiv_daily/retriever/chemrxiv_retriever.py`
- [Retriever framework](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/retriever/base.py): `src/zotero_arxiv_daily/retriever/base.py`

### Relevance ranking

- [Relevance scoring](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/base.py): `src/zotero_arxiv_daily/reranker/base.py`
- [Local embeddings](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/local.py): `src/zotero_arxiv_daily/reranker/local.py`
- [Embedding API](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/reranker/api.py): `src/zotero_arxiv_daily/reranker/api.py`

### Paper enrichment

- [Paper records](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py): `src/zotero_arxiv_daily/protocol.py`
- [LLM enrichment](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/protocol.py): `src/zotero_arxiv_daily/protocol.py`
- [PDF and TeX extraction](https://github.com/tidedra/zotero-arxiv-daily/blob/main/src/zotero_arxiv_daily/utils.py): `src/zotero_arxiv_daily/utils.py`

### Other components

- **Scheduled run**
- **Mailbox recipient**
- **LLM service**
- **Preprint services**
- **Embedding service**

## Connections

- Scheduled run → Application entry: starts (evidence: `README.md`)
- Application entry → Workflow executor: runs (evidence: `src/zotero_arxiv_daily/main.py`)
- Runtime configuration → Workflow executor: configures (evidence: `README.md`)
- Workflow executor → Zotero library: fetches library (evidence: `src/zotero_arxiv_daily/executor.py`)
- Workflow executor → Collection filtering: filters corpus (evidence: `src/zotero_arxiv_daily/executor.py`)
- Workflow executor → Library corpus: builds corpus (evidence: `src/zotero_arxiv_daily/executor.py`)
- Workflow executor → Retriever framework: selects retrievers (evidence: `src/zotero_arxiv_daily/executor.py`)
- Retriever framework → arXiv retrieval: registers (evidence: `src/zotero_arxiv_daily/retriever/__init__.py`)
- Retriever framework → bioRxiv retrieval: registers (evidence: `src/zotero_arxiv_daily/retriever/__init__.py`)
- Retriever framework → medRxiv retrieval: registers (evidence: `src/zotero_arxiv_daily/retriever/__init__.py`)
- Retriever framework → chemRxiv retrieval: registers (evidence: `src/zotero_arxiv_daily/retriever/__init__.py`)
- arXiv retrieval → Preprint services: queries (evidence: `src/zotero_arxiv_daily/retriever/arxiv_retriever.py`)
- bioRxiv retrieval → Preprint services: queries (evidence: `src/zotero_arxiv_daily/retriever/biorxiv_retriever.py`)
- chemRxiv retrieval → Preprint services: queries Crossref (evidence: `src/zotero_arxiv_daily/retriever/chemrxiv_retriever.py`)
- Workflow executor → Relevance scoring: reranks papers (evidence: `src/zotero_arxiv_daily/executor.py`)
- Relevance scoring → Local embeddings: uses scorer (evidence: `src/zotero_arxiv_daily/reranker/base.py`)
- Relevance scoring → Embedding API: uses scorer (evidence: `src/zotero_arxiv_daily/reranker/base.py`)
- Embedding API → Embedding service: requests embeddings (evidence: `src/zotero_arxiv_daily/reranker/api.py`)
- Workflow executor → LLM enrichment: enriches selected papers (evidence: `src/zotero_arxiv_daily/executor.py`)
- LLM enrichment → LLM service: requests summaries and affiliations (evidence: `src/zotero_arxiv_daily/protocol.py`)
- arXiv retrieval → PDF and TeX extraction: extracts text (evidence: `src/zotero_arxiv_daily/retriever/arxiv_retriever.py`)
- Workflow executor → Digest rendering: renders digest (evidence: `src/zotero_arxiv_daily/executor.py`)
- Workflow executor → SMTP delivery: sends digest (evidence: `src/zotero_arxiv_daily/executor.py`)
- SMTP delivery → Mailbox recipient: delivers email (evidence: `src/zotero_arxiv_daily/utils.py`)
- Digest rendering → Paper records: formats paper details (evidence: `README.md`)
- Paper records → Mailbox recipient: provides PDF and code links (evidence: `README.md`)
