# bge-barcoding/beegees architecture

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

- Interactive diagram: https://gitdiagram.com/bge-barcoding/beegees
- Repository: https://github.com/bge-barcoding/beegees

## Overview

BeeGees is a Snakemake bioinformatics workflow that turns genome-skim reads into cleaned, validated COI-5P or rbcL barcode sequences, per-sample metrics, and a MultiQC report. The user supplies sample metadata and configuration, then starts the run through the CLI. The README documents the major workflow stages and outputs; implementation of the Snakefile and several stages was not sampled, so those documented connections cite the README rather than implying source inspection.

Main entry points: [`beegees/workflow`](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow) (Read preprocessing), [`beegees/__main__.py`](https://github.com/bge-barcoding/beegees/blob/main/beegees/__main__.py) (BeeGees CLI), [`beegees/workflow/scripts/01_human_mitogenome_filter.py`](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/01_human_mitogenome_filter.py) (Human contamination filter), [`beegees/workflow/scripts/05_consensus_generator.py`](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/05_consensus_generator.py) (Clean consensus generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Run setup"]
  node_config["Run configuration<br/>[config.yaml]"]
  node_cli["BeeGees CLI<br/>[__main__.py]"]
  node_config_utils["Workflow file lookup<br/>[configs.py]"]
  node_snakemake_args["Command builder<br/>[snakemake_args.py]"]
end

subgraph group_recovery["Read processing and recovery"]
  node_snakemake["Snakemake workflow"]
  node_preprocess["Read preprocessing"]
  node_gene_fetch["Reference retrieval"]
  node_mitogene["Barcode recovery"]
  node_consensus_prep["Consensus preparation<br/>[rename_headers.py]"]
end

subgraph group_cleaning["Consensus cleaning"]
  node_human_filter["Human contamination filter"]
  node_at_filter["AT content filter"]
  node_outlier_filter["Outlier filter"]
  node_reference_filter["Reference filter"]
  node_consensus_clean["Clean consensus generation"]
end

subgraph group_validation["Barcode validation"]
  node_structural["Structural validation"]
  node_blast["Local BLAST search<br/>[tv_local_blast.py]"]
  node_taxonomy["Taxonomic validation"]
end

subgraph group_outputs["Reports and metrics"]
  node_final_fasta["Validated barcode FASTA"]
  node_metrics["Combined metrics CSV<br/>[val_csv_merger.py]"]
  node_filter_metrics["Filter metrics aggregation"]
  node_report["MultiQC report"]
end

node_user(("Researcher"))
node_samples["Read files and samples"]

node_user -->|"starts run"| node_cli
node_user -->|"provides reads"| node_samples
node_user -->|"configures run"| node_config
node_cli -->|"builds command"| node_snakemake_args
node_snakemake_args -->|"locates workflow"| node_config_utils
node_cli -->|"launches"| node_snakemake
node_snakemake -->|"runs"| node_preprocess
node_samples -->|"supplies reads"| node_preprocess
node_preprocess -->|"feeds run"| node_gene_fetch
node_gene_fetch -->|"provides references"| node_mitogene
node_mitogene -->|"produces consensuses"| node_consensus_prep
node_consensus_prep -->|"feeds alignments"| node_human_filter
node_human_filter -->|"filters sequences"| node_at_filter
node_at_filter -->|"filters outliers"| node_outlier_filter
node_outlier_filter -->|"filters references"| node_reference_filter
node_reference_filter -->|"generates consensus"| node_consensus_clean
node_consensus_clean -->|"validates structure"| node_structural
node_consensus_clean -->|"searches taxonomy"| node_blast
node_blast -->|"supplies hits"| node_taxonomy
node_structural -->|"selects barcodes"| node_final_fasta
node_taxonomy -->|"validates taxonomy"| node_final_fasta
node_human_filter -->|"records filter metrics"| node_filter_metrics
node_filter_metrics -->|"contributes metrics"| node_metrics
node_taxonomy -->|"records validation"| node_metrics
node_preprocess -->|"reports QC"| node_report
node_metrics -->|"summarizes results"| node_report

click node_config "https://github.com/bge-barcoding/beegees/blob/main/beegees/config/config.yaml"
click node_cli "https://github.com/bge-barcoding/beegees/blob/main/beegees/__main__.py"
click node_config_utils "https://github.com/bge-barcoding/beegees/blob/main/beegees/utils/configs.py"
click node_snakemake_args "https://github.com/bge-barcoding/beegees/blob/main/beegees/utils/snakemake_args.py"
click node_snakemake "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/Snakefile"
click node_preprocess "https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow"
click node_gene_fetch "https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow"
click node_mitogene "https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow"
click node_consensus_prep "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/rename_headers.py"
click node_human_filter "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/01_human_mitogenome_filter.py"
click node_at_filter "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/02_at_content_filter.py"
click node_outlier_filter "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/03_statistical_outlier_filter.py"
click node_reference_filter "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/04_reference_filter.py"
click node_consensus_clean "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/05_consensus_generator.py"
click node_structural "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/structural_validation.py"
click node_blast "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/tv_local_blast.py"
click node_taxonomy "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/tv_blast2taxonomy.py"
click node_final_fasta "https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow"
click node_metrics "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/val_csv_merger.py"
click node_filter_metrics "https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/06_aggregate_filter_metrics.py"
click node_report "https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow"

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_config,node_cli,node_config_utils,node_snakemake_args toneBlue
class node_snakemake,node_preprocess,node_gene_fetch,node_mitogene,node_consensus_prep toneAmber
class node_human_filter,node_at_filter,node_outlier_filter,node_reference_filter,node_consensus_clean toneMint
class node_structural,node_blast,node_taxonomy toneRose
class node_final_fasta,node_metrics,node_filter_metrics,node_report,node_user,node_samples toneIndigo
```

## Components

### Run setup

- [Run configuration](https://github.com/bge-barcoding/beegees/blob/main/beegees/config/config.yaml): `beegees/config/config.yaml`
- [BeeGees CLI](https://github.com/bge-barcoding/beegees/blob/main/beegees/__main__.py): `beegees/__main__.py`
- [Workflow file lookup](https://github.com/bge-barcoding/beegees/blob/main/beegees/utils/configs.py): `beegees/utils/configs.py`
- [Command builder](https://github.com/bge-barcoding/beegees/blob/main/beegees/utils/snakemake_args.py): `beegees/utils/snakemake_args.py`

### Read processing and recovery

- [Snakemake workflow](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/Snakefile): `beegees/workflow/Snakefile`
- [Read preprocessing](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow): `beegees/workflow`
- [Reference retrieval](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow): `beegees/workflow`
- [Barcode recovery](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow): `beegees/workflow`
- [Consensus preparation](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/rename_headers.py): `beegees/workflow/scripts/rename_headers.py`

### Consensus cleaning

- [Human contamination filter](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/01_human_mitogenome_filter.py): `beegees/workflow/scripts/01_human_mitogenome_filter.py`
- [AT content filter](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/02_at_content_filter.py): `beegees/workflow/scripts/02_at_content_filter.py`
- [Outlier filter](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/03_statistical_outlier_filter.py): `beegees/workflow/scripts/03_statistical_outlier_filter.py`
- [Reference filter](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/04_reference_filter.py): `beegees/workflow/scripts/04_reference_filter.py`
- [Clean consensus generation](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/05_consensus_generator.py): `beegees/workflow/scripts/05_consensus_generator.py`

### Barcode validation

- [Structural validation](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/structural_validation.py): `beegees/workflow/scripts/structural_validation.py`
- [Local BLAST search](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/tv_local_blast.py): `beegees/workflow/scripts/tv_local_blast.py`
- [Taxonomic validation](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/tv_blast2taxonomy.py): `beegees/workflow/scripts/tv_blast2taxonomy.py`

### Reports and metrics

- [Validated barcode FASTA](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow): `beegees/workflow`
- [Combined metrics CSV](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/val_csv_merger.py): `beegees/workflow/scripts/val_csv_merger.py`
- [Filter metrics aggregation](https://github.com/bge-barcoding/beegees/blob/main/beegees/workflow/scripts/06_aggregate_filter_metrics.py): `beegees/workflow/scripts/06_aggregate_filter_metrics.py`
- [MultiQC report](https://github.com/bge-barcoding/beegees/tree/main/beegees/workflow): `beegees/workflow`

### Other components

- **Researcher**
- **Read files and samples**

## Connections

- Researcher → BeeGees CLI: starts run (evidence: `README.md`)
- Researcher → Read files and samples: provides reads (evidence: `README.md`)
- Researcher → Run configuration: configures run (evidence: `README.md`)
- BeeGees CLI → Command builder: builds command (evidence: `beegees/__main__.py`)
- Command builder → Workflow file lookup: locates workflow (evidence: `beegees/utils/snakemake_args.py`)
- BeeGees CLI → Snakemake workflow: launches (evidence: `beegees/__main__.py`)
- Snakemake workflow → Read preprocessing: runs (evidence: `README.md`)
- Read files and samples → Read preprocessing: supplies reads (evidence: `README.md`)
- Read preprocessing → Reference retrieval: feeds run (evidence: `README.md`)
- Reference retrieval → Barcode recovery: provides references (evidence: `README.md`)
- Barcode recovery → Consensus preparation: produces consensuses (evidence: `README.md`)
- Consensus preparation → Human contamination filter: feeds alignments (evidence: `README.md`)
- Human contamination filter → AT content filter: filters sequences (evidence: `README.md`)
- AT content filter → Outlier filter: filters outliers (evidence: `README.md`)
- Outlier filter → Reference filter: filters references (evidence: `README.md`)
- Reference filter → Clean consensus generation: generates consensus (evidence: `README.md`)
- Clean consensus generation → Structural validation: validates structure (evidence: `README.md`)
- Clean consensus generation → Local BLAST search: searches taxonomy (evidence: `README.md`)
- Local BLAST search → Taxonomic validation: supplies hits (evidence: `README.md`)
- Structural validation → Validated barcode FASTA: selects barcodes (evidence: `README.md`)
- Taxonomic validation → Validated barcode FASTA: validates taxonomy (evidence: `README.md`)
- Human contamination filter → Filter metrics aggregation: records filter metrics (evidence: `beegees/workflow/scripts/01_human_mitogenome_filter.py`)
- Filter metrics aggregation → Combined metrics CSV: contributes metrics (evidence: `README.md`)
- Taxonomic validation → Combined metrics CSV: records validation (evidence: `README.md`)
- Read preprocessing → MultiQC report: reports QC (evidence: `README.md`)
- Combined metrics CSV → MultiQC report: summarizes results (evidence: `README.md`)
