# cdcgov/aquascope architecture

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

- Interactive diagram: https://gitdiagram.com/cdcgov/aquascope
- Repository: https://github.com/cdcgov/aquascope

## Overview

Aquascope is a Nextflow bioinformatics pipeline for SARS-CoV-2 wastewater sequencing that aims to determine relative variant abundance. The graph shows the documented user-to-result purpose and major workflow branches suggested by the repository layout. The README does not describe internal routing, and the supplied source excerpts cover only samplesheet utilities, so internal workflow connections are shown as unverified rather than asserted as source-proven calls.

Main entry points: [`workflows/aquascope.nf`](https://github.com/cdcgov/aquascope/blob/main/workflows/aquascope.nf) (Aquascope workflow), [`subworkflows/local/freyja_variant_demix_update/main.nf`](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/freyja_variant_demix_update/main.nf) (Freyja orchestration), [`workflows/freyja_only.nf`](https://github.com/cdcgov/aquascope/blob/main/workflows/freyja_only.nf) (Freyja workflow), [`main.nf`](https://github.com/cdcgov/aquascope/blob/main/main.nf) (Nextflow entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Pipeline entry"]
  node_entrypoint["Nextflow entry<br/>[main.nf]"]
  node_aquascope["Aquascope workflow<br/>[aquascope.nf]"]
  node_freyja_only["Freyja workflow<br/>[freyja_only.nf]"]
  node_quality_align["Quality alignment<br/>[quality_align.nf]"]
end

subgraph group_preprocess["Input and trimming"]
  node_samplesheet["Samplesheet validation"]
  node_bam_sheet["BAM samplesheet"]
  node_input_check["Input checks<br/>[input_check.nf]"]
  node_trimming["Read trimming<br/>[trimming.nf]"]
  node_ont_trimming["ONT trimming<br/>[ont_trimming.nf]"]
end

subgraph group_analysis["Alignment and QC"]
  node_alignment["Read alignment<br/>[main.nf]"]
  node_bam_stats["BAM sort and stats<br/>[main.nf]"]
  node_qc["Sequencing QC<br/>[main.nf]"]
  node_multiqc["QC report<br/>[main.nf]"]
end

subgraph group_variants["Variant analysis"]
  node_freyja_pipeline["Freyja orchestration<br/>[main.nf]"]
  node_freyja_variants["Variant calling<br/>[main.nf]"]
  node_freyja_demix["Variant demixing<br/>[main.nf]"]
  node_freyja_update["Freyja reference update<br/>[main.nf]"]
end

node_user(("Pipeline user"))
node_abundance["Relative variant abundance"]

node_user -->|"runs pipeline"| node_entrypoint
node_entrypoint -.->|"starts workflow"| node_aquascope
node_aquascope -.->|"validates inputs"| node_samplesheet
node_aquascope -.->|"checks inputs"| node_input_check
node_aquascope -.->|"trims reads"| node_trimming
node_aquascope -.->|"trims ONT reads"| node_ont_trimming
node_aquascope -.->|"aligns reads"| node_alignment
node_aquascope -.->|"processes BAMs"| node_bam_stats
node_aquascope -.->|"assesses quality"| node_qc
node_aquascope -.->|"reports QC"| node_multiqc
node_aquascope -.->|"analyzes variants"| node_freyja_pipeline
node_freyja_only -.->|"prepares BAM inputs"| node_bam_sheet
node_freyja_only -.->|"runs analysis"| node_freyja_pipeline
node_freyja_pipeline -.->|"updates reference"| node_freyja_update
node_freyja_pipeline -.->|"calls variants"| node_freyja_variants
node_freyja_pipeline -.->|"demixes variants"| node_freyja_demix
node_freyja_pipeline -.->|"produces abundance"| node_abundance
node_quality_align -.->|"aligns reads"| node_alignment

click node_entrypoint "https://github.com/cdcgov/aquascope/blob/main/main.nf"
click node_aquascope "https://github.com/cdcgov/aquascope/blob/main/workflows/aquascope.nf"
click node_freyja_only "https://github.com/cdcgov/aquascope/blob/main/workflows/freyja_only.nf"
click node_quality_align "https://github.com/cdcgov/aquascope/blob/main/workflows/quality_align.nf"
click node_samplesheet "https://github.com/cdcgov/aquascope/blob/main/bin/check_samplesheet.py"
click node_bam_sheet "https://github.com/cdcgov/aquascope/blob/main/bin/bam_to_samplesheet.py"
click node_input_check "https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/input_check.nf"
click node_trimming "https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/trimming.nf"
click node_ont_trimming "https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/ont_trimming.nf"
click node_alignment "https://github.com/cdcgov/aquascope/blob/main/modules/local/minimap2/align/main.nf"
click node_bam_stats "https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/bam_sort_stats_samtools/main.nf"
click node_qc "https://github.com/cdcgov/aquascope/blob/main/modules/nf-core/qualimap/bamqc/main.nf"
click node_multiqc "https://github.com/cdcgov/aquascope/blob/main/modules/nf-core/multiqc/main.nf"
click node_freyja_pipeline "https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/freyja_variant_demix_update/main.nf"
click node_freyja_variants "https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/variants/main.nf"
click node_freyja_demix "https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/demix/main.nf"
click node_freyja_update "https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/update/main.nf"

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_entrypoint,node_aquascope,node_freyja_only,node_quality_align,node_user toneBlue
class node_samplesheet,node_bam_sheet,node_input_check,node_trimming,node_ont_trimming toneAmber
class node_alignment,node_bam_stats,node_qc,node_multiqc toneMint
class node_freyja_pipeline,node_freyja_variants,node_freyja_demix,node_freyja_update toneRose
class node_abundance toneIndigo
```

## Components

### Pipeline entry

- [Nextflow entry](https://github.com/cdcgov/aquascope/blob/main/main.nf): `main.nf`
- [Aquascope workflow](https://github.com/cdcgov/aquascope/blob/main/workflows/aquascope.nf): `workflows/aquascope.nf`
- [Freyja workflow](https://github.com/cdcgov/aquascope/blob/main/workflows/freyja_only.nf): `workflows/freyja_only.nf`
- [Quality alignment](https://github.com/cdcgov/aquascope/blob/main/workflows/quality_align.nf): `workflows/quality_align.nf`

### Input and trimming

- [Samplesheet validation](https://github.com/cdcgov/aquascope/blob/main/bin/check_samplesheet.py): `bin/check_samplesheet.py`
- [BAM samplesheet](https://github.com/cdcgov/aquascope/blob/main/bin/bam_to_samplesheet.py): `bin/bam_to_samplesheet.py`
- [Input checks](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/input_check.nf): `subworkflows/local/input_check.nf`
- [Read trimming](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/trimming.nf): `subworkflows/local/trimming.nf`
- [ONT trimming](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/ont_trimming.nf): `subworkflows/local/ont_trimming.nf`

### Alignment and QC

- [Read alignment](https://github.com/cdcgov/aquascope/blob/main/modules/local/minimap2/align/main.nf): `modules/local/minimap2/align/main.nf`
- [BAM sort and stats](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/bam_sort_stats_samtools/main.nf): `subworkflows/local/bam_sort_stats_samtools/main.nf`
- [Sequencing QC](https://github.com/cdcgov/aquascope/blob/main/modules/nf-core/qualimap/bamqc/main.nf): `modules/nf-core/qualimap/bamqc/main.nf`
- [QC report](https://github.com/cdcgov/aquascope/blob/main/modules/nf-core/multiqc/main.nf): `modules/nf-core/multiqc/main.nf`

### Variant analysis

- [Freyja orchestration](https://github.com/cdcgov/aquascope/blob/main/subworkflows/local/freyja_variant_demix_update/main.nf): `subworkflows/local/freyja_variant_demix_update/main.nf`
- [Variant calling](https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/variants/main.nf): `modules/local/freyja/variants/main.nf`
- [Variant demixing](https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/demix/main.nf): `modules/local/freyja/demix/main.nf`
- [Freyja reference update](https://github.com/cdcgov/aquascope/blob/main/modules/local/freyja/update/main.nf): `modules/local/freyja/update/main.nf`

### Other components

- **Pipeline user**
- **Relative variant abundance**

## Connections

- Pipeline user → Nextflow entry: runs pipeline (evidence: `README.md`)
- Nextflow entry → Aquascope workflow: starts workflow
- Aquascope workflow → Samplesheet validation: validates inputs
- Aquascope workflow → Input checks: checks inputs
- Aquascope workflow → Read trimming: trims reads
- Aquascope workflow → ONT trimming: trims ONT reads
- Aquascope workflow → Read alignment: aligns reads
- Aquascope workflow → BAM sort and stats: processes BAMs
- Aquascope workflow → Sequencing QC: assesses quality
- Aquascope workflow → QC report: reports QC
- Aquascope workflow → Freyja orchestration: analyzes variants
- Freyja workflow → BAM samplesheet: prepares BAM inputs
- Freyja workflow → Freyja orchestration: runs analysis
- Freyja orchestration → Freyja reference update: updates reference
- Freyja orchestration → Variant calling: calls variants
- Freyja orchestration → Variant demixing: demixes variants
- Freyja orchestration → Relative variant abundance: produces abundance
- Quality alignment → Read alignment: aligns reads
