# gene2dis/bugbuster architecture

> Architecture diagram of the GitHub repository gene2dis/bugbuster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gene2dis/bugbuster
- Repository: https://github.com/gene2dis/bugbuster

## Overview

##### Main Components
- Nextflow Orchestrator and Pipeline Entry: The central engine is the “main.nf” file at the project root, which controls the overall workflow.
- Modules: Under the “modules” directory, there is a clear modular breakdown—each subdirectory (such as “arg_fasta_formatter”, “fastp”, “bowtie2”, “metabat2”, etc.) contains its own Nextflow process script (main.nf). Each module represents a step in the pipeline (e.g., read QC, host contamination removal, taxonomic profiling, genome assembly, binning, etc.).
- Configuration Files: The “nextflow.config” and files in the “config” directory (e.g., “databases.config”, “modules.config”) hold parameters, resource allocation defaults, and paths to external databases.
- Input/Output Artifacts: The pipeline uses a “samplesheet.csv” as its input, and it produces multiple outputs (reports, intermediate files, final results) based on the different stages.

##### Component Relationships and Interactions
- The Nextflow engine (main.nf) acts as a central controller. It dynamically invokes each module as a process, ensuring that the output from one step becomes the input to the next.
- Each module (packed in its own container) runs specific tasks (e.g., FastP for read QC, Bowtie2 for host contamination removal, Kraken2 and Sourmash for taxonomic profiling, Megahit for assembly, BlobTools for contig annotation) and may interact with external APIs/databases.
- The configuration files supply pipeline parameters, including database paths for various tools (Bowtie2, Kraken2, nt DB, etc.), which are key to ensuring reproducibility and accurate resource usage.
- Read-level analysis, assembly, and binning components interact sequentially in the workflow, with “assembly_mode” configuration controlling how assembly is conducted (coassembly vs individual assembly).

##### Architectural Patterns and Design Principles
- Modular Design: Every analytical step is compartmentalized into its own module. This makes the pipeline easy to update or extend.
- Containerized Execution: Every process is launched in its individual Docker container. This encapsulation ensures that all software dependencies remain consistent and promotes reproducibility.
- Workflow Orchestration: Nextflow’s design ensures that processes are executed according to dependencies and configured resource constraints across compute infrastructures.
- Configuration-driven Behavior: The numerous configuration files separate code from settings such as database paths or parameter defaults—this is central for flexible deployment across different environments.

##### Relevant Technologies and Frameworks
- Nextflow DSL2 – the workflow engine.
- Docker – containerization for each process.
- A suite of bioinformatics tools: FastP, Bowtie2, Kraken2, Bracken, Megahit, BlobTools, MetaCerberus, Prodigal, DeepARG, Metabat2, SemiBin, COMEBin, MetaWrap, CheckM2, GTDB-TK, and MMseqs2.
- Various external databases (e.g., nt, gtdbtk data, human_db, and more) as part of the configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration & Configuration Layer
    subgraph "Pipeline Orchestration & Configuration"
        samplesheet["samplesheet.csv"]:::input
        nextflowEngine["Nextflow Pipeline Engine"]:::orchestration
        nextflowConfig["Nextflow Config File"]:::config
        configDir["Config Directory"]:::config
    end

    %% Modular Processing Layer
    subgraph "Modular Processing"
        moduleFastP["Module: FastP - Read QC"]:::module
        moduleBowtie2["Module: Bowtie2 - Host Removal"]:::module
        moduleSamtools["Module: Samtools Processing"]:::module
        moduleKraken2["Module: Kraken2 - Taxonomic Profiling"]:::module
        moduleSourmash["Module: Sourmash - Taxonomic Profiling"]:::module
        moduleMegahit["Module: Megahit - Genome Assembly"]:::module
        moduleMetabat2["Module: Metabat2 - Binning"]:::module
    end

    %% External Dependencies
    subgraph "External Dependencies"
        externalDeps["External Databases & Docker Containers"]:::external
    end

    %% Data Flow Connections
    samplesheet -->|"feeds"| nextflowEngine
    nextflowConfig -->|"configures"| nextflowEngine
    configDir -->|"supplements"| nextflowEngine

    nextflowEngine -->|"triggers"| moduleFastP
    moduleFastP -->|"outputs cleansed reads"| moduleBowtie2
    moduleBowtie2 -->|"processes data"| moduleSamtools
    moduleSamtools -->|"splits data"| moduleKraken2
    moduleSamtools -->|"splits data"| moduleSourmash
    moduleSamtools -->|"passes reads"| moduleMegahit
    moduleMegahit -->|"assembled contigs"| moduleMetabat2

    %% Configuration influence on modules
    nextflowConfig -.->|"provides parameters"| moduleFastP
    nextflowConfig -.->|"provides parameters"| moduleBowtie2
    nextflowConfig -.->|"provides parameters"| moduleSamtools
    nextflowConfig -.->|"provides parameters"| moduleKraken2
    nextflowConfig -.->|"provides parameters"| moduleSourmash
    nextflowConfig -.->|"provides parameters"| moduleMegahit
    nextflowConfig -.->|"provides parameters"| moduleMetabat2
    configDir -.->|"provides supplementary configs"| moduleFastP
    configDir -.->|"provides supplementary configs"| moduleBowtie2
    configDir -.->|"provides supplementary configs"| moduleKraken2
    configDir -.->|"provides supplementary configs"| moduleMegahit

    %% External Dependencies from specific modules and configuration
    moduleBowtie2 -.->|"queries"| externalDeps
    moduleKraken2 -.->|"queries"| externalDeps
    nextflowConfig -.->|"defines DB paths"| externalDeps

    %% Click Events
    click samplesheet "https://github.com/gene2dis/bugbuster/blob/main/samplesheet.csv"
    click nextflowEngine "https://github.com/gene2dis/bugbuster/blob/main/main.nf"
    click nextflowConfig "https://github.com/gene2dis/bugbuster/blob/main/nextflow.config"
    click configDir "https://github.com/gene2dis/bugbuster/tree/main/config"
    click moduleFastP "https://github.com/gene2dis/bugbuster/blob/main/modules/fastp/main.nf"
    click moduleBowtie2 "https://github.com/gene2dis/bugbuster/blob/main/modules/bowtie2/main.nf"
    click moduleSamtools "https://github.com/gene2dis/bugbuster/blob/main/modules/bowtie2_samtools/main.nf"
    click moduleKraken2 "https://github.com/gene2dis/bugbuster/blob/main/modules/kraken2/main.nf"
    click moduleSourmash "https://github.com/gene2dis/bugbuster/blob/main/modules/sourmash/main.nf"
    click moduleMegahit "https://github.com/gene2dis/bugbuster/blob/main/modules/megahit/main.nf"
    click moduleMetabat2 "https://github.com/gene2dis/bugbuster/blob/main/modules/metabat2/main.nf"

    %% Styles
    classDef input fill:#ffe6f0,stroke:#b30059,stroke-width:2px;
    classDef orchestration fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef module fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
