# sourmash-bio/sourmash architecture

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

- Interactive diagram: https://gitdiagram.com/sourmash-bio/sourmash
- Repository: https://github.com/sourmash-bio/sourmash

## Overview

sourmash is a Python/Rust genomic k-mer analysis toolkit. A typical workflow sketches sequence data into signatures, stores or indexes signatures, then searches, gathers, compares, or classifies results. The map also preserves documented metagenomic profiling, ANI, taxonomy, and signature-management capabilities. Relationships shown from README statements are cited there; source-level links use the available excerpts or SOURCE INDEX references, so unsampled implementation details are not represented as verified calls.

Main entry points: [`src/sourmash/commands.py`](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/commands.py) (CLI commands), [`src/sourmash/minhash.py`](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/minhash.py) (MinHash engine), [`src/sourmash/search.py`](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/search.py) (Search and gather), [`src/sourmash/index/__init__.py`](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/index/__init__.py) (Index API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sketching["Sketching and signatures"]
  node_sketch_cli["Sketch commands<br/>[dna.py]"]
  node_compute["Sketch generation<br/>[command_sketch.py]"]
  node_minhash["MinHash engine<br/>[minhash.py]"]
  node_signatures["Signatures<br/>[signature.py]"]
  node_rust_signature["Core signatures<br/>[signature.rs]"]
end

subgraph group_analysis["Search and analysis"]
  node_search["Search and gather<br/>[search.py]"]
  node_compare["Comparison<br/>[compare.py]"]
  node_distance["Distance and ANI<br/>[distance_utils.py]"]
end

subgraph group_collections["Indexes and storage"]
  node_manifest["Collection manifest<br/>[manifest.py]"]
  node_index_api["Index API<br/>[__init__.py]"]
  node_sqlite[("SQLite index<br/>[sqlite_index.py]")]
  node_reverse_index[("Rust reverse index<br/>[mod.rs]")]
  node_storage[("Signature storage<br/>[mod.rs]")]
  node_sbt[("SBT indexes<br/>[sbt.py]")]
end

subgraph group_taxonomy["Taxonomy and LCA"]
  node_lca[("LCA database<br/>[lca_db.py]")]
  node_tax["Taxonomy analysis<br/>[tax_utils.py]"]
  node_lca_commands["LCA commands<br/>[index.py]"]
  node_tax_commands["Taxonomy commands<br/>[__main__.py]"]
end

node_user(("Researcher"))
node_cli["CLI commands<br/>[commands.py]"]

node_user -->|"runs"| node_cli
node_cli -.->|"dispatches"| node_sketch_cli
node_sketch_cli -.->|"requests sketches"| node_compute
node_compute -.->|"creates"| node_signatures
node_signatures -->|"contains sketches"| node_minhash
node_rust_signature -->|"adds sequences"| node_minhash
node_cli -->|"runs search or gather"| node_search
node_search -->|"searches index"| node_index_api
node_search -->|"compares sketches"| node_minhash
node_cli -->|"runs comparison"| node_compare
node_compare -.->|"calculates distances"| node_distance
node_distance -.->|"uses sketch metrics"| node_minhash
node_index_api -->|"selects signatures"| node_manifest
node_sqlite -->|"uses manifest"| node_manifest
node_sqlite -.->|"queries hashes"| node_reverse_index
node_storage -->|"loads signatures"| node_rust_signature
node_index_api -.->|"supports SBT indexes"| node_sbt
node_cli -.->|"runs LCA commands"| node_lca_commands
node_lca_commands -.->|"builds index"| node_lca
node_lca -->|"uses taxonomy utilities"| node_tax
node_cli -.->|"runs taxonomy analysis"| node_tax_commands
node_tax_commands -->|"uses taxonomy"| node_tax

click node_cli "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/commands.py"
click node_sketch_cli "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/cli/sketch/dna.py"
click node_compute "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/command_sketch.py"
click node_minhash "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/minhash.py"
click node_signatures "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/signature.py"
click node_rust_signature "https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/signature.rs"
click node_search "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/search.py"
click node_compare "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/compare.py"
click node_distance "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/distance_utils.py"
click node_manifest "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/manifest.py"
click node_index_api "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/index/__init__.py"
click node_sqlite "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/index/sqlite_index.py"
click node_reverse_index "https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/index/revindex/mod.rs"
click node_storage "https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/storage/mod.rs"
click node_sbt "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/sbt.py"
click node_lca "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/lca/lca_db.py"
click node_tax "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/tax/tax_utils.py"
click node_lca_commands "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/cli/lca/index.py"
click node_tax_commands "https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/tax/__main__.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_sketch_cli,node_compute,node_minhash,node_signatures,node_rust_signature toneBlue
class node_search,node_compare,node_distance toneAmber
class node_manifest,node_index_api,node_sqlite,node_reverse_index,node_storage,node_sbt toneMint
class node_lca,node_tax,node_lca_commands,node_tax_commands toneRose
class node_user toneIndigo
class node_cli toneTeal
```

## Components

### Sketching and signatures

- [Sketch commands](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/cli/sketch/dna.py): `src/sourmash/cli/sketch/dna.py`
- [Sketch generation](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/command_sketch.py): `src/sourmash/command_sketch.py`
- [MinHash engine](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/minhash.py): `src/sourmash/minhash.py`
- [Signatures](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/signature.py): `src/sourmash/signature.py`
- [Core signatures](https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/signature.rs): `src/core/src/signature.rs`

### Search and analysis

- [Search and gather](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/search.py): `src/sourmash/search.py`
- [Comparison](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/compare.py): `src/sourmash/compare.py`
- [Distance and ANI](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/distance_utils.py): `src/sourmash/distance_utils.py`

### Indexes and storage

- [Collection manifest](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/manifest.py): `src/sourmash/manifest.py`
- [Index API](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/index/__init__.py): `src/sourmash/index/__init__.py`
- [SQLite index](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/index/sqlite_index.py): `src/sourmash/index/sqlite_index.py`
- [Rust reverse index](https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/index/revindex/mod.rs): `src/core/src/index/revindex/mod.rs`
- [Signature storage](https://github.com/sourmash-bio/sourmash/blob/latest/src/core/src/storage/mod.rs): `src/core/src/storage/mod.rs`
- [SBT indexes](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/sbt.py): `src/sourmash/sbt.py`

### Taxonomy and LCA

- [LCA database](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/lca/lca_db.py): `src/sourmash/lca/lca_db.py`
- [Taxonomy analysis](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/tax/tax_utils.py): `src/sourmash/tax/tax_utils.py`
- [LCA commands](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/cli/lca/index.py): `src/sourmash/cli/lca/index.py`
- [Taxonomy commands](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/tax/__main__.py): `src/sourmash/tax/__main__.py`

### Other components

- **Researcher**
- [CLI commands](https://github.com/sourmash-bio/sourmash/blob/latest/src/sourmash/commands.py): `src/sourmash/commands.py`

## Connections

- Researcher → CLI commands: runs (evidence: `README.md`)
- CLI commands → Sketch commands: dispatches
- Sketch commands → Sketch generation: requests sketches
- Sketch generation → Signatures: creates
- Signatures → MinHash engine: contains sketches (evidence: `src/sourmash/signature.py`)
- Core signatures → MinHash engine: adds sequences (evidence: `src/core/src/signature.rs`)
- CLI commands → Search and gather: runs search or gather (evidence: `README.md`)
- Search and gather → Index API: searches index (evidence: `src/sourmash/index/__init__.py`)
- Search and gather → MinHash engine: compares sketches (evidence: `src/sourmash/search.py`)
- CLI commands → Comparison: runs comparison (evidence: `README.md`)
- Comparison → Distance and ANI: calculates distances
- Distance and ANI → MinHash engine: uses sketch metrics (evidence: `src/sourmash/minhash.py`)
- Index API → Collection manifest: selects signatures (evidence: `src/sourmash/index/__init__.py`)
- SQLite index → Collection manifest: uses manifest (evidence: `src/sourmash/index/sqlite_index.py`)
- SQLite index → Rust reverse index: queries hashes
- Signature storage → Core signatures: loads signatures (evidence: `src/core/src/storage/mod.rs`)
- Index API → SBT indexes: supports SBT indexes
- CLI commands → LCA commands: runs LCA commands
- LCA commands → LCA database: builds index
- LCA database → Taxonomy analysis: uses taxonomy utilities (evidence: `src/sourmash/lca/lca_db.py`)
- CLI commands → Taxonomy commands: runs taxonomy analysis
- Taxonomy commands → Taxonomy analysis: uses taxonomy (evidence: `src/sourmash/tax/__main__.py`)
