# bbushnell/bbtools architecture

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

- Interactive diagram: https://gitdiagram.com/bbushnell/bbtools
- Repository: https://github.com/bbushnell/bbtools
- Video tour (about a minute): https://gitdiagram.com/bbushnell/bbtools/video

## Overview

BBTools is a suite of independent command-line bioinformatics tools, not one end-to-end application. Its principal user workflow is to provide sequencing reads (and, where needed, references or databases), run a tool suited to the task, and receive processed reads, alignments, assembly output, or analysis results. Major documented branches include read mapping, quality control, correction, assembly, and read organization; the tree also shows barcode demultiplexing, coverage analysis, and clade/sketch search. The README documents capabilities beyond the sampled source, so this map shows tool-level workflows rather than unverified internal call chains.

Main entry points: [`current/clade/SendClade.java`](https://github.com/bbushnell/bbtools/blob/master/current/clade/SendClade.java) (Remote organism search), [`current/barcode/DemuxClient.java`](https://github.com/bbushnell/bbtools/blob/master/current/barcode/DemuxClient.java) (Barcode demultiplexing), [`current/align2/BBMap.java`](https://github.com/bbushnell/bbtools/blob/master/current/align2/BBMap.java) (BBMap mapping), [`current/jgi/CoveragePileup.java`](https://github.com/bbushnell/bbtools/blob/master/current/jgi/CoveragePileup.java) (Coverage analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Mapping and analysis"]
  node_bbmap["BBMap mapping<br/>[BBMap.java]"]
  node_coverage["Coverage analysis"]
end

subgraph group_readprep["Read preparation"]
  node_bbduk["Trim and filter<br/>[BBDuk3.java]"]
  node_bbnorm["Normalize and correct"]
  node_bbmerge["Paired-read merging"]
  node_clumpify["Read organization<br/>[Clumpify.java]"]
end

subgraph group_assembly["Assembly"]
  node_tadpole["Tadpole assembly<br/>[Tadpole.java]"]
end

subgraph group_sketch["Sketch and taxonomy"]
  node_sendclade["Remote organism search<br/>[SendClade.java]"]
  node_queryresult["Ranked matches<br/>[QueryResult.java]"]
end

subgraph group_other["Other workflows"]
  node_demux["Barcode demultiplexing<br/>[DemuxClient.java]"]
end

node_user(("Sequencing user"))
node_reads["Reads and references"]
node_mapped["Mapped reads"]
node_coverageout["Coverage reports"]
node_cleanreads["Cleaned reads"]
node_corrected["Corrected reads"]
node_merged["Merged reads"]
node_organized["Organized reads"]
node_assemblyout["Assembly output"]
node_cladeserver(("Clade search service"))
node_demuxserver(("Demultiplexing service"))
node_demuxout["Barcode assignments"]

node_user -->|"provides"| node_reads
node_reads -->|"map against reference"| node_bbmap
node_bbmap -->|"writes alignments"| node_mapped
node_mapped -->|"analyze coverage"| node_coverage
node_coverage -->|"reports coverage"| node_coverageout
node_reads -->|"trim and filter"| node_bbduk
node_bbduk -->|"writes reads"| node_cleanreads
node_reads -->|"correct or normalize"| node_bbnorm
node_bbnorm -->|"writes reads"| node_corrected
node_reads -->|"merge pairs"| node_bbmerge
node_bbmerge -->|"writes merged reads"| node_merged
node_reads -->|"reorder reads"| node_clumpify
node_clumpify -->|"writes reads"| node_organized
node_reads -->|"assemble or correct"| node_tadpole
node_tadpole -->|"writes results"| node_assemblyout
node_user -->|"submit organism query"| node_sendclade
node_sendclade -.->|"queries remotely"| node_cladeserver
node_sendclade -.->|"returns matches"| node_queryresult
node_reads -->|"submit barcode data"| node_demux
node_demux -.->|"requests assignments"| node_demuxserver
node_demux -->|"returns assignments"| node_demuxout

click node_bbmap "https://github.com/bbushnell/bbtools/blob/master/current/align2/BBMap.java"
click node_coverage "https://github.com/bbushnell/bbtools/blob/master/current/jgi/CoveragePileup.java"
click node_bbduk "https://github.com/bbushnell/bbtools/blob/master/current/bbduk/BBDuk3.java"
click node_bbnorm "https://github.com/bbushnell/bbtools/blob/master/current/bloom/BloomFilterCorrectorWrapper.java"
click node_clumpify "https://github.com/bbushnell/bbtools/blob/master/current/clump/Clumpify.java"
click node_tadpole "https://github.com/bbushnell/bbtools/blob/master/current/assemble/Tadpole.java"
click node_sendclade "https://github.com/bbushnell/bbtools/blob/master/current/clade/SendClade.java"
click node_queryresult "https://github.com/bbushnell/bbtools/blob/master/current/clade/QueryResult.java"
click node_demux "https://github.com/bbushnell/bbtools/blob/master/current/barcode/DemuxClient.java"

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_bbmap,node_coverage,node_user toneBlue
class node_bbduk,node_bbnorm,node_bbmerge,node_clumpify toneAmber
class node_tadpole toneMint
class node_sendclade,node_queryresult toneRose
class node_demux,node_reads,node_mapped,node_coverageout,node_cleanreads,node_corrected,node_merged,node_organized,node_assemblyout,node_cladeserver,node_demuxserver,node_demuxout toneIndigo
```

## Components

### Mapping and analysis

- [BBMap mapping](https://github.com/bbushnell/bbtools/blob/master/current/align2/BBMap.java): `current/align2/BBMap.java`
- [Coverage analysis](https://github.com/bbushnell/bbtools/blob/master/current/jgi/CoveragePileup.java): `current/jgi/CoveragePileup.java`

### Read preparation

- [Trim and filter](https://github.com/bbushnell/bbtools/blob/master/current/bbduk/BBDuk3.java): `current/bbduk/BBDuk3.java`
- [Normalize and correct](https://github.com/bbushnell/bbtools/blob/master/current/bloom/BloomFilterCorrectorWrapper.java): `current/bloom/BloomFilterCorrectorWrapper.java`
- **Paired-read merging**
- [Read organization](https://github.com/bbushnell/bbtools/blob/master/current/clump/Clumpify.java): `current/clump/Clumpify.java`

### Assembly

- [Tadpole assembly](https://github.com/bbushnell/bbtools/blob/master/current/assemble/Tadpole.java): `current/assemble/Tadpole.java`

### Sketch and taxonomy

- [Remote organism search](https://github.com/bbushnell/bbtools/blob/master/current/clade/SendClade.java): `current/clade/SendClade.java`
- [Ranked matches](https://github.com/bbushnell/bbtools/blob/master/current/clade/QueryResult.java): `current/clade/QueryResult.java`

### Other workflows

- [Barcode demultiplexing](https://github.com/bbushnell/bbtools/blob/master/current/barcode/DemuxClient.java): `current/barcode/DemuxClient.java`

### Other components

- **Sequencing user**
- **Reads and references**
- **Mapped reads**
- **Coverage reports**
- **Cleaned reads**
- **Corrected reads**
- **Merged reads**
- **Organized reads**
- **Assembly output**
- **Clade search service**
- **Demultiplexing service**
- **Barcode assignments**

## Connections

- Sequencing user → Reads and references: provides
- Reads and references → BBMap mapping: map against reference
- BBMap mapping → Mapped reads: writes alignments
- Mapped reads → Coverage analysis: analyze coverage
- Coverage analysis → Coverage reports: reports coverage
- Reads and references → Trim and filter: trim and filter
- Trim and filter → Cleaned reads: writes reads
- Reads and references → Normalize and correct: correct or normalize
- Normalize and correct → Corrected reads: writes reads
- Reads and references → Paired-read merging: merge pairs
- Paired-read merging → Merged reads: writes merged reads
- Reads and references → Read organization: reorder reads
- Read organization → Organized reads: writes reads
- Reads and references → Tadpole assembly: assemble or correct
- Tadpole assembly → Assembly output: writes results
- Sequencing user → Remote organism search: submit organism query
- Remote organism search → Clade search service: queries remotely
- Remote organism search → Ranked matches: returns matches
- Reads and references → Barcode demultiplexing: submit barcode data
- Barcode demultiplexing → Demultiplexing service: requests assignments
- Barcode demultiplexing → Barcode assignments: returns assignments