# filcivilini/boltpy architecture

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

- Interactive diagram: https://gitdiagram.com/filcivilini/boltpy
- Repository: https://github.com/filcivilini/boltpy

## Overview

boltpy is a Python toolkit for literature-review harvesting and triage. A user configures keywords, selected sources, result ceilings, dates, and optional credentials, then calls `harvest`; the toolkit queries sources, cleans and deduplicates records, and returns full and ASReview-ready data plus PRISMA counters and export paths. The graph groups the runtime by configuration/orchestration, source integrations, record processing, and outputs. Provider coverage and several capabilities are documented in the README but their implementation details were not sampled, so those links cite the README rather than implying inspected internals.

Main entry points: [`src/boltpy/core.py`](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py) (Harvest coordinator), [`src/boltpy`](https://github.com/filcivilini/boltpy/tree/main/src/boltpy) (arXiv provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Harvest orchestration"]
  node_config["Harvest config<br/>[core.py]"]
  node_harvest["Harvest coordinator<br/>[core.py]"]
end

subgraph group_sources["Literature sources"]
  node_crossref["Crossref provider<br/>[core.py]"]
  node_openalex["OpenAlex provider<br/>[core.py]"]
  node_pubmed["PubMed provider<br/>[core.py]"]
  node_arxiv["arXiv provider"]
  node_europepmc["Europe PMC provider"]
  node_zenodo["Zenodo provider<br/>[core.py]"]
  node_scopus["Scopus provider"]
end

subgraph group_processing["Record processing"]
  node_cleaning["Metadata cleaning<br/>[core.py]"]
  node_dedup["Record deduplication<br/>[core.py]"]
end

subgraph group_outputs["Triage outputs"]
  node_exports["Exports and counters<br/>[core.py]"]
  node_results["Harvest results<br/>[core.py]"]
end

node_reviewer(("Literature reviewer"))
node_scholarly_apis{{"Scholarly APIs"}}

node_reviewer -->|"sets options"| node_config
node_reviewer -->|"calls"| node_harvest
node_harvest -->|"uses"| node_config
node_harvest -->|"queries"| node_crossref
node_harvest -->|"queries"| node_openalex
node_harvest -->|"queries"| node_pubmed
node_harvest -->|"queries"| node_arxiv
node_harvest -->|"queries"| node_europepmc
node_harvest -->|"queries"| node_zenodo
node_harvest -.->|"queries"| node_scopus
node_crossref -->|"requests metadata"| node_scholarly_apis
node_openalex -->|"requests metadata"| node_scholarly_apis
node_pubmed -->|"searches and fetches"| node_scholarly_apis
node_zenodo -->|"requests metadata"| node_scholarly_apis
node_harvest -->|"cleans records"| node_cleaning
node_harvest -->|"deduplicates"| node_dedup
node_harvest -->|"exports and counts"| node_exports
node_harvest -->|"returns"| node_results
node_exports -->|"provides paths"| node_results

click node_config "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_harvest "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_crossref "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_openalex "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_pubmed "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_arxiv "https://github.com/filcivilini/boltpy/tree/main/src/boltpy"
click node_europepmc "https://github.com/filcivilini/boltpy/tree/main/src/boltpy"
click node_zenodo "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_scopus "https://github.com/filcivilini/boltpy/tree/main/src/boltpy"
click node_cleaning "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_dedup "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_exports "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py"
click node_results "https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.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_config,node_harvest,node_reviewer toneBlue
class node_crossref,node_openalex,node_pubmed,node_arxiv,node_europepmc,node_zenodo,node_scopus toneAmber
class node_cleaning,node_dedup,node_scholarly_apis toneMint
class node_exports,node_results toneRose
```

## Components

### Harvest orchestration

- [Harvest config](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [Harvest coordinator](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`

### Literature sources

- [Crossref provider](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [OpenAlex provider](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [PubMed provider](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [arXiv provider](https://github.com/filcivilini/boltpy/tree/main/src/boltpy): `src/boltpy`
- [Europe PMC provider](https://github.com/filcivilini/boltpy/tree/main/src/boltpy): `src/boltpy`
- [Zenodo provider](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [Scopus provider](https://github.com/filcivilini/boltpy/tree/main/src/boltpy): `src/boltpy`

### Record processing

- [Metadata cleaning](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [Record deduplication](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`

### Triage outputs

- [Exports and counters](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`
- [Harvest results](https://github.com/filcivilini/boltpy/blob/main/src/boltpy/core.py): `src/boltpy/core.py`

### Other components

- **Literature reviewer**
- **Scholarly APIs**

## Connections

- Literature reviewer → Harvest config: sets options (evidence: `README.md`)
- Literature reviewer → Harvest coordinator: calls (evidence: `README.md`)
- Harvest coordinator → Harvest config: uses (evidence: `README.md`)
- Harvest coordinator → Crossref provider: queries (evidence: `README.md`)
- Harvest coordinator → OpenAlex provider: queries (evidence: `README.md`)
- Harvest coordinator → PubMed provider: queries (evidence: `README.md`)
- Harvest coordinator → arXiv provider: queries (evidence: `README.md`)
- Harvest coordinator → Europe PMC provider: queries (evidence: `README.md`)
- Harvest coordinator → Zenodo provider: queries (evidence: `README.md`)
- Harvest coordinator → Scopus provider: queries (evidence: `README.md`)
- Crossref provider → Scholarly APIs: requests metadata (evidence: `src/boltpy/core.py`)
- OpenAlex provider → Scholarly APIs: requests metadata (evidence: `src/boltpy/core.py`)
- PubMed provider → Scholarly APIs: searches and fetches (evidence: `src/boltpy/core.py`)
- Zenodo provider → Scholarly APIs: requests metadata (evidence: `src/boltpy/core.py`)
- Harvest coordinator → Metadata cleaning: cleans records (evidence: `README.md`)
- Harvest coordinator → Record deduplication: deduplicates (evidence: `README.md`)
- Harvest coordinator → Exports and counters: exports and counts (evidence: `README.md`)
- Harvest coordinator → Harvest results: returns (evidence: `README.md`)
- Exports and counters → Harvest results: provides paths (evidence: `README.md`)
