# bge-barcoding/boldcurator architecture

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

## Overview

BOLDcurator’s Python app curates barcode records offline from a local BOLD snapshot. A curator opens the desktop interface, selects a snapshot and search criteria, then receives expanded and filtered specimen results with rankings, BAGS grades, BIN analysis and representative selections. The interface also supports phylogeny, annotations, saved sessions and exports. The graph follows documented pipeline stages and source-index references; unsampled implementations are represented only where the tree supports a path, and uncertain connections are omitted.

Main entry points: [`python/src/boldcurator/ui/app.py`](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/app.py) (Curation interface), [`python/src/boldcurator/core/pipeline.py`](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/pipeline.py) (Search pipeline), [`python/src/boldcurator/ui/state.py`](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/state.py) (UI state), [`python/src/boldcurator/io/session.py`](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/session.py) (Saved sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and setup"]
  node_desktop["Desktop host<br/>[desktop.py]"]
  node_setup["Snapshot setup<br/>[setup.py]"]
  node_ui["Curation interface<br/>[app.py]"]
  node_state["UI state<br/>[state.py]"]
  node_updates["App updates<br/>[app_update.py]"]
end

subgraph group_data["Snapshot and search"]
  node_snapshot[("Snapshot store<br/>[snapshot.py]")]
  node_schema["Snapshot schema<br/>[schema.py]"]
  node_queries["Taxon and record queries<br/>[queries.py]"]
end

subgraph group_analysis["Curation analysis"]
  node_pipeline["Search pipeline<br/>[pipeline.py]"]
  node_species["Species handling<br/>[species.py]"]
  node_ranking["Specimen ranking<br/>[ranking.py]"]
  node_scoring["Metadata scoring<br/>[scoring.py]"]
  node_bags["BAGS grading<br/>[bags.py]"]
  node_bins["BIN analysis<br/>[bins.py]"]
  node_selection["Representative selection<br/>[selection.py]"]
end

subgraph group_curation["Review and output"]
  node_grouping["Review groups<br/>[grouping.py]"]
  node_table["Result tables<br/>[table.py]"]
  node_phylogeny["Phylogeny<br/>[phylogeny.py]"]
  node_refalign["Reference alignment<br/>[refalign.py]"]
  node_annotations["Record annotations<br/>[annotations.py]"]
  node_sessions[("Saved sessions<br/>[session.py]")]
  node_exports["Curated exports<br/>[exports.py]"]
  node_summaries["Analysis summaries<br/>[summaries.py]"]
end

node_curator(("Curator"))

node_curator -->|"launches"| node_desktop
node_desktop -->|"opens setup"| node_setup
node_desktop -->|"hosts app"| node_ui
node_setup -->|"selects snapshot"| node_snapshot
node_ui -->|"updates state"| node_state
node_ui -->|"uses review groups"| node_grouping
node_ui -->|"renders results"| node_table
node_ui -->|"offers phylogeny"| node_phylogeny
node_ui -->|"edits annotations"| node_annotations
node_ui -->|"saves sessions"| node_sessions
node_ui -->|"downloads results"| node_exports
node_ui -->|"checks updates"| node_updates
node_state -->|"runs search"| node_pipeline
node_state -->|"uses ranking"| node_ranking
node_state -->|"builds groups"| node_grouping
node_state -->|"tracks annotations"| node_annotations
node_state -->|"persists sessions"| node_sessions
node_state -->|"prepares exports"| node_exports
node_pipeline -->|"fetches records"| node_queries
node_pipeline -->|"reads snapshot"| node_snapshot
node_pipeline -->|"ranks specimens"| node_ranking
node_pipeline -->|"grades species"| node_bags
node_pipeline -->|"analyses BINs"| node_bins
node_pipeline -->|"selects representatives"| node_selection
node_ranking -->|"scores records"| node_scoring
node_bags -->|"checks species names"| node_species
node_bins -->|"uses shared-BIN logic"| node_bags
node_queries -->|"queries data"| node_snapshot
node_queries -->|"uses schema"| node_schema
node_snapshot -->|"validates against"| node_schema
node_phylogeny -->|"uses alignment"| node_refalign
node_phylogeny -->|"uses selections"| node_selection
node_table -->|"displays results"| node_pipeline
node_table -->|"joins annotations"| node_annotations
node_exports -->|"exports annotations"| node_annotations
node_exports -->|"fetches sequences"| node_queries
node_exports -->|"reads snapshot data"| node_snapshot
node_sessions -->|"restores search"| node_pipeline
node_sessions -->|"stores annotations"| node_annotations
node_sessions -->|"uses record schema"| node_schema

click node_desktop "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/desktop.py"
click node_setup "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/setup.py"
click node_ui "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/app.py"
click node_state "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/state.py"
click node_snapshot "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/snapshot.py"
click node_schema "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/schema.py"
click node_queries "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/queries.py"
click node_pipeline "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/pipeline.py"
click node_species "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/species.py"
click node_ranking "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/ranking.py"
click node_scoring "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/scoring.py"
click node_bags "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/bags.py"
click node_bins "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/bins.py"
click node_selection "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/selection.py"
click node_grouping "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/grouping.py"
click node_table "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/table.py"
click node_phylogeny "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/phylogeny.py"
click node_refalign "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/refalign.py"
click node_annotations "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/annotations.py"
click node_sessions "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/session.py"
click node_exports "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/exports.py"
click node_summaries "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/summaries.py"
click node_updates "https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/app_update.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_desktop,node_setup,node_ui,node_state,node_updates toneBlue
class node_snapshot,node_schema,node_queries toneAmber
class node_pipeline,node_species,node_ranking,node_scoring,node_bags,node_bins,node_selection toneMint
class node_grouping,node_table,node_phylogeny,node_refalign,node_annotations,node_sessions,node_exports,node_summaries toneRose
class node_curator toneIndigo
```

## Components

### App and setup

- [Desktop host](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/desktop.py): `python/src/boldcurator/desktop.py`
- [Snapshot setup](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/setup.py): `python/src/boldcurator/ui/setup.py`
- [Curation interface](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/app.py): `python/src/boldcurator/ui/app.py`
- [UI state](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/ui/state.py): `python/src/boldcurator/ui/state.py`
- [App updates](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/app_update.py): `python/src/boldcurator/app_update.py`

### Snapshot and search

- [Snapshot store](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/snapshot.py): `python/src/boldcurator/data/snapshot.py`
- [Snapshot schema](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/schema.py): `python/src/boldcurator/data/schema.py`
- [Taxon and record queries](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/data/queries.py): `python/src/boldcurator/data/queries.py`

### Curation analysis

- [Search pipeline](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/pipeline.py): `python/src/boldcurator/core/pipeline.py`
- [Species handling](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/species.py): `python/src/boldcurator/core/species.py`
- [Specimen ranking](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/ranking.py): `python/src/boldcurator/core/ranking.py`
- [Metadata scoring](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/scoring.py): `python/src/boldcurator/core/scoring.py`
- [BAGS grading](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/bags.py): `python/src/boldcurator/core/bags.py`
- [BIN analysis](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/bins.py): `python/src/boldcurator/core/bins.py`
- [Representative selection](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/selection.py): `python/src/boldcurator/core/selection.py`

### Review and output

- [Review groups](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/grouping.py): `python/src/boldcurator/core/grouping.py`
- [Result tables](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/table.py): `python/src/boldcurator/core/table.py`
- [Phylogeny](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/phylogeny.py): `python/src/boldcurator/core/phylogeny.py`
- [Reference alignment](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/refalign.py): `python/src/boldcurator/core/refalign.py`
- [Record annotations](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/annotations.py): `python/src/boldcurator/io/annotations.py`
- [Saved sessions](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/session.py): `python/src/boldcurator/io/session.py`
- [Curated exports](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/io/exports.py): `python/src/boldcurator/io/exports.py`
- [Analysis summaries](https://github.com/bge-barcoding/boldcurator/blob/main/python/src/boldcurator/core/summaries.py): `python/src/boldcurator/core/summaries.py`

### Other components

- **Curator**

## Connections

- Curator → Desktop host: launches (evidence: `README.md`)
- Desktop host → Snapshot setup: opens setup (evidence: `python/src/boldcurator/desktop.py`)
- Desktop host → Curation interface: hosts app (evidence: `python/src/boldcurator/desktop.py`)
- Snapshot setup → Snapshot store: selects snapshot (evidence: `python/src/boldcurator/ui/setup.py`)
- Curation interface → UI state: updates state (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Review groups: uses review groups (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Result tables: renders results (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Phylogeny: offers phylogeny (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Record annotations: edits annotations (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Saved sessions: saves sessions (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → Curated exports: downloads results (evidence: `python/src/boldcurator/ui/app.py`)
- Curation interface → App updates: checks updates (evidence: `python/src/boldcurator/ui/app.py`)
- UI state → Search pipeline: runs search (evidence: `python/src/boldcurator/ui/state.py`)
- UI state → Specimen ranking: uses ranking (evidence: `python/src/boldcurator/ui/state.py`)
- UI state → Review groups: builds groups (evidence: `python/src/boldcurator/ui/state.py`)
- UI state → Record annotations: tracks annotations (evidence: `python/src/boldcurator/ui/state.py`)
- UI state → Saved sessions: persists sessions (evidence: `python/src/boldcurator/ui/state.py`)
- UI state → Curated exports: prepares exports (evidence: `python/src/boldcurator/ui/state.py`)
- Search pipeline → Taxon and record queries: fetches records (evidence: `python/src/boldcurator/core/pipeline.py`)
- Search pipeline → Snapshot store: reads snapshot (evidence: `python/src/boldcurator/core/pipeline.py`)
- Search pipeline → Specimen ranking: ranks specimens (evidence: `python/src/boldcurator/core/pipeline.py`)
- Search pipeline → BAGS grading: grades species (evidence: `python/src/boldcurator/core/pipeline.py`)
- Search pipeline → BIN analysis: analyses BINs (evidence: `python/src/boldcurator/core/pipeline.py`)
- Search pipeline → Representative selection: selects representatives (evidence: `python/src/boldcurator/core/pipeline.py`)
- Specimen ranking → Metadata scoring: scores records (evidence: `python/src/boldcurator/core/ranking.py`)
- BAGS grading → Species handling: checks species names (evidence: `python/src/boldcurator/core/bags.py`)
- BIN analysis → BAGS grading: uses shared-BIN logic (evidence: `python/src/boldcurator/core/bins.py`)
- Taxon and record queries → Snapshot store: queries data (evidence: `python/src/boldcurator/data/queries.py`)
- Taxon and record queries → Snapshot schema: uses schema (evidence: `python/src/boldcurator/data/queries.py`)
- Snapshot store → Snapshot schema: validates against (evidence: `python/src/boldcurator/data/snapshot.py`)
- Phylogeny → Reference alignment: uses alignment (evidence: `python/src/boldcurator/core/phylogeny.py`)
- Phylogeny → Representative selection: uses selections (evidence: `python/src/boldcurator/core/phylogeny.py`)
- Result tables → Search pipeline: displays results (evidence: `python/src/boldcurator/core/table.py`)
- Result tables → Record annotations: joins annotations (evidence: `python/src/boldcurator/core/table.py`)
- Curated exports → Record annotations: exports annotations (evidence: `python/src/boldcurator/io/exports.py`)
- Curated exports → Taxon and record queries: fetches sequences (evidence: `python/src/boldcurator/io/exports.py`)
- Curated exports → Snapshot store: reads snapshot data (evidence: `python/src/boldcurator/io/exports.py`)
- Saved sessions → Search pipeline: restores search (evidence: `python/src/boldcurator/io/session.py`)
- Saved sessions → Record annotations: stores annotations (evidence: `python/src/boldcurator/io/session.py`)
- Saved sessions → Snapshot schema: uses record schema (evidence: `python/src/boldcurator/io/session.py`)
