# fulcrumgenomics/fgbio architecture

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

- Interactive diagram: https://gitdiagram.com/fulcrumgenomics/fgbio
- Repository: https://github.com/fulcrumgenomics/fgbio

## Overview

fgbio is a command-line toolkit for genomic and next-generation sequencing analysis. Users invoke focused tools on read-level or variant-level data; capabilities include FASTQ processing and demultiplexing, BAM manipulation, UMI consensus workflows, reference-file utilities, variant operations, and quality-control metrics. The graph groups these product areas and includes the shared command-line and SAM/BAM foundations. The README documents the tool capabilities and broad input types; sampled source excerpts are incomplete, so internal links between individual tools are omitted where their calls are not shown.

Main entry points: [`src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala`](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala) (Tool commands), [`src/main/scala/com/fulcrumgenomics/fastq/DemuxFastqs.scala`](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fastq/DemuxFastqs.scala) (FASTQ tools), [`src/main/scala/com/fulcrumgenomics/bam/FilterBam.scala`](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/FilterBam.scala) (BAM tools), [`src/main/scala/com/fulcrumgenomics/umi/AnnotateBamWithUmis.scala`](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/AnnotateBamWithUmis.scala) (UMI annotation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command line"]
  node_commands["Tool commands<br/>[FgBioMain.scala]"]
  node_tool_api["Tool API<br/>[FgBioTool.scala]"]
  node_shared_defs["Shared definitions<br/>[FgBioDef.scala]"]
end

subgraph group_reads["Read processing"]
  node_fastq_tools["FASTQ tools<br/>[DemuxFastqs.scala]"]
  node_fastq_io["FASTQ I/O<br/>[FastqSource.scala]"]
  node_bam_tools["BAM tools<br/>[FilterBam.scala]"]
  node_bam_core["BAM utilities<br/>[Bams.scala]"]
  node_sam_source["SAM reader<br/>[SamSource.scala]"]
  node_sam_record["SAM records<br/>[SamRecord.scala]"]
  node_sam_writer["SAM writer<br/>[SamWriter.scala]"]
  node_sample["Sample metadata<br/>[Sample.scala]"]
end

subgraph group_umi["UMI workflows"]
  node_umi_annotation["UMI annotation"]
  node_umi_grouping["UMI grouping"]
  node_consensus["Consensus reads"]
  node_consensus_tags["Consensus tags"]
end

subgraph group_reference["Reference and variants"]
  node_fasta_tools["FASTA tools"]
  node_sequence_dict["Sequence dictionary"]
  node_vcf_tools["VCF tools"]
  node_variant_api["Variant model<br/>[Variant.scala]"]
end

subgraph group_qc["Quality control"]
  node_read_qc["Read QC"]
  node_rna_qc["RNA-seq QC"]
  node_metrics["Metrics<br/>[Metric.scala]"]
end

node_user(("Bioinformatics user"))
node_read_inputs["FASTQ / BAM inputs"]

node_user -->|"runs"| node_commands
node_commands -->|"runs"| node_fastq_tools
node_commands -->|"runs"| node_bam_tools
node_commands -->|"runs"| node_umi_annotation
node_commands -->|"runs"| node_umi_grouping
node_commands -->|"runs"| node_consensus
node_commands -->|"runs"| node_fasta_tools
node_commands -->|"runs"| node_vcf_tools
node_commands -->|"runs"| node_read_qc
node_commands -->|"runs"| node_rna_qc
node_read_inputs -->|"provides reads"| node_fastq_tools
node_read_inputs -->|"provides reads"| node_bam_tools

click node_commands "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala"
click node_tool_api "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/cmdline/FgBioTool.scala"
click node_fastq_tools "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fastq/DemuxFastqs.scala"
click node_fastq_io "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fastq/FastqSource.scala"
click node_bam_tools "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/FilterBam.scala"
click node_bam_core "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/Bams.scala"
click node_sam_source "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamSource.scala"
click node_sam_record "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamRecord.scala"
click node_sam_writer "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamWriter.scala"
click node_umi_annotation "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/AnnotateBamWithUmis.scala"
click node_umi_grouping "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/GroupReadsByUmi.scala"
click node_consensus "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/CallMolecularConsensusReads.scala"
click node_consensus_tags "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/ConsensusTags.scala"
click node_fasta_tools "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fasta/UpdateFastaContigNames.scala"
click node_sequence_dict "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fasta/SequenceDictionary.scala"
click node_vcf_tools "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/vcf/MakeMixtureVcf.scala"
click node_variant_api "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/vcf/api/Variant.scala"
click node_read_qc "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/ErrorRateByReadPosition.scala"
click node_rna_qc "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/rnaseq/EstimateRnaSeqInsertSize.scala"
click node_metrics "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/util/Metric.scala"
click node_sample "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/illumina/Sample.scala"
click node_shared_defs "https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/FgBioDef.scala"

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_commands,node_tool_api,node_shared_defs,node_user toneBlue
class node_fastq_tools,node_fastq_io,node_bam_tools,node_bam_core,node_sam_source,node_sam_record,node_sam_writer,node_sample toneAmber
class node_umi_annotation,node_umi_grouping,node_consensus,node_consensus_tags toneMint
class node_fasta_tools,node_sequence_dict,node_vcf_tools,node_variant_api toneRose
class node_read_qc,node_rna_qc,node_metrics,node_read_inputs toneIndigo
```

## Components

### Command line

- [Tool commands](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala): `src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala`
- [Tool API](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/cmdline/FgBioTool.scala): `src/main/scala/com/fulcrumgenomics/cmdline/FgBioTool.scala`
- [Shared definitions](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/FgBioDef.scala): `src/main/scala/com/fulcrumgenomics/FgBioDef.scala`

### Read processing

- [FASTQ tools](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fastq/DemuxFastqs.scala): `src/main/scala/com/fulcrumgenomics/fastq/DemuxFastqs.scala`
- [FASTQ I/O](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fastq/FastqSource.scala): `src/main/scala/com/fulcrumgenomics/fastq/FastqSource.scala`
- [BAM tools](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/FilterBam.scala): `src/main/scala/com/fulcrumgenomics/bam/FilterBam.scala`
- [BAM utilities](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/Bams.scala): `src/main/scala/com/fulcrumgenomics/bam/Bams.scala`
- [SAM reader](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamSource.scala): `src/main/scala/com/fulcrumgenomics/bam/api/SamSource.scala`
- [SAM records](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamRecord.scala): `src/main/scala/com/fulcrumgenomics/bam/api/SamRecord.scala`
- [SAM writer](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/api/SamWriter.scala): `src/main/scala/com/fulcrumgenomics/bam/api/SamWriter.scala`
- [Sample metadata](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/illumina/Sample.scala): `src/main/scala/com/fulcrumgenomics/illumina/Sample.scala`

### UMI workflows

- [UMI annotation](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/AnnotateBamWithUmis.scala): `src/main/scala/com/fulcrumgenomics/umi/AnnotateBamWithUmis.scala`
- [UMI grouping](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/GroupReadsByUmi.scala): `src/main/scala/com/fulcrumgenomics/umi/GroupReadsByUmi.scala`
- [Consensus reads](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/CallMolecularConsensusReads.scala): `src/main/scala/com/fulcrumgenomics/umi/CallMolecularConsensusReads.scala`
- [Consensus tags](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/umi/ConsensusTags.scala): `src/main/scala/com/fulcrumgenomics/umi/ConsensusTags.scala`

### Reference and variants

- [FASTA tools](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fasta/UpdateFastaContigNames.scala): `src/main/scala/com/fulcrumgenomics/fasta/UpdateFastaContigNames.scala`
- [Sequence dictionary](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/fasta/SequenceDictionary.scala): `src/main/scala/com/fulcrumgenomics/fasta/SequenceDictionary.scala`
- [VCF tools](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/vcf/MakeMixtureVcf.scala): `src/main/scala/com/fulcrumgenomics/vcf/MakeMixtureVcf.scala`
- [Variant model](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/vcf/api/Variant.scala): `src/main/scala/com/fulcrumgenomics/vcf/api/Variant.scala`

### Quality control

- [Read QC](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/bam/ErrorRateByReadPosition.scala): `src/main/scala/com/fulcrumgenomics/bam/ErrorRateByReadPosition.scala`
- [RNA-seq QC](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/rnaseq/EstimateRnaSeqInsertSize.scala): `src/main/scala/com/fulcrumgenomics/rnaseq/EstimateRnaSeqInsertSize.scala`
- [Metrics](https://github.com/fulcrumgenomics/fgbio/blob/main/src/main/scala/com/fulcrumgenomics/util/Metric.scala): `src/main/scala/com/fulcrumgenomics/util/Metric.scala`

### Other components

- **Bioinformatics user**
- **FASTQ / BAM inputs**

## Connections

- Bioinformatics user → Tool commands: runs (evidence: `README.md`)
- Tool commands → FASTQ tools: runs (evidence: `README.md`)
- Tool commands → BAM tools: runs (evidence: `README.md`)
- Tool commands → UMI annotation: runs (evidence: `README.md`)
- Tool commands → UMI grouping: runs (evidence: `README.md`)
- Tool commands → Consensus reads: runs (evidence: `README.md`)
- Tool commands → FASTA tools: runs (evidence: `README.md`)
- Tool commands → VCF tools: runs (evidence: `README.md`)
- Tool commands → Read QC: runs (evidence: `README.md`)
- Tool commands → RNA-seq QC: runs (evidence: `README.md`)
- FASTQ / BAM inputs → FASTQ tools: provides reads (evidence: `README.md`)
- FASTQ / BAM inputs → BAM tools: provides reads (evidence: `README.md`)