# nf-core/scrnaseq architecture

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

- Interactive diagram: https://gitdiagram.com/nf-core/scrnaseq
- Repository: https://github.com/nf-core/scrnaseq

## Overview

##### Project Type and Purpose
- The project is a bioinformatics analysis pipeline (specifically scRNA-seq) that automates several data processing paths for single-cell RNA sequencing.
- Its purpose is to standardize and modularize the processing of 10x Genomics single-cell RNA-seq data using best-practice workflows and multiple aligners.
- The README and file organization (with modules for each tool, test configurations, and workflow subdirectories) confirm that this is a Nextflow-driven, container-enabled full pipeline.

##### File Structure to Extract Architectural Components
- The top-level structure shows various configuration files (nextflow.config, nf-core.yml, .pre-commit-config.yaml, etc.) that define global pipeline parameters and environment details.
- The directories "modules" and "subworkflows" indicate that the workflow is modularized: one part (“modules/nf-core”) contains standard modules for individual tools (e.g., CellRanger, fastqc, gffread, etc.), while "modules/local" contains local versions or supplementary modules.
- The “conf” directory holds different configuration profiles (base, test, and genome configurations) which play a central role in parameterizing the pipeline's execution.
- The “bin” directory contains script wrappers for various helper functions (like quality control and preprocessing steps).
- The existence of CI/CD configuration files under .github/workflows, as well as Docker and Singularity configuration (via container profiles), indicates a strong emphasis on reproducibility and continuous validation.

##### README for Additional Insights
- The README introduces the pipeline’s major functionality and highlights its support for various aligners.
- There are instructions for running the pipeline with different containerization profiles, which points to the integration of Docker, Singularity, and Conda environments.
- The discussion about licensing, collaboration, and continuous integration (with GitHub workflows) reinforces the importance of modular design and robust orchestration.

##### Key Components
a. Main Workflow Engine:
- Nextflow orchestrator (main.nf and nextflow.config) coordinating the overall pipeline execution.
b. Input Management:
- Command-line interface for accepting input (samplesheet and pipeline parameters).
- Initial sample parsing and configuration modules.
c. Modular Processing Units:
- Individual modules under “modules/nf-core” and “modules/local” that implement specific processing tasks (e.g., alignment, counting, data conversion).
- Branching paths for different aligners; each branch includes its own set of tasks (e.g., Alevin-Fry with AlevinQC, STARsolo, CellRanger, etc.).
d. Auxiliary Workflows and Subworkflows:
- “subworkflows” directory contents indicating reusable building blocks and wrappers for integrated bioinformatics analysis.
e. Output and Reporting Components:
- Final output consolidation (reports, h5ad/seurat/mtx matrices).
- Quality control and postprocessing steps (e.g., AlevinQC, multiqc integration) that process and summarize the output.

##### Relationships and Interactions Between Components
- From input (sample sheets, configuration parameters) into the main Nextflow process.
- From the central orchestrator to individual processing modules.
- From each alignment branch to a consolidation/reporting step.
- Dependencies such as the usage of container images (Docker/Singularity) and Conda environments to ensure reproducibility.
- That modules not only process data in series but may also run in parallel based on available computational resources.

##### Incorporate Key Architectural Patterns and Technologies
- Micro-modular architecture: Emphasize the separation between individual processing modules.
- Containerization: Clearly denote that individual modules run within containerized environments to ensure consistency.
- Workflow orchestration by Nextflow DSL2: Illustrate robust pipeline control, error management, and scalability.
- Config-driven behavior: Highlight the use of multiple config files (in “conf”) that dictate different execution profiles (e.g., test, full, and cellranger-specific configurations).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Management Layer
    subgraph "Input Management"
        A("Sample Sheet Input"):::input
        B("Sample Parsing Module"):::input
    end

    %% Workflow Engine Layer
    subgraph "Workflow Engine"
        M("Nextflow Orchestrator (main.nf)"):::orchestrator
        N("Nextflow Configuration (nextflow.config)"):::orchestrator
    end

    %% Modular Processing Units
    subgraph "Modular Processing Units"
        %% CellRanger Processing
        subgraph "CellRanger Processing"
            CR1("CellRanger Single-sample (count)"):::processor
            CR2("CellRanger Multi-sample"):::processor
        end
        %% STARsolo Alignment
        subgraph "STARsolo Alignment"
            S1("STARsolo Alignment Module"):::processor
            S2("STARsolo Subworkflow"):::processor
        end
        %% Alevin-Fry Processing
        subgraph "Alevin-Fry Processing"
            AF1("Alevin-Fry Quantification"):::processor
            AF2("Alevin-Fry Index Building"):::processor
            AF3("Alevin-Fry Quality Control"):::processor
        end
        %% Kallisto/BUStools Processing
        subgraph "Kallisto/BUStools Processing"
            KB1("Kallisto/BUStools Counting"):::processor
            KB2("Kallisto/BUStools Reference Generation"):::processor
        end
        %% QC and Transcriptome Preparation
        subgraph "Quality Control & Preparation"
            FQC("FastQC Module"):::processor
            GG1("GFFread Standard Module"):::processor
            GG2("Local Transcriptome Conversion"):::processor
        end
        %% Output Conversion and Reporting
        subgraph "Output Conversion and Reporting"
            O1("Matrix to h5ad Conversion"):::output
            O2("Concatenation of Output Files"):::output
        end
    end

    %% Auxiliary Workflows
    subgraph "Auxiliary Workflows"
        AW("Reusable Alignment/Postprocessing"):::auxiliary
    end

    %% Configuration Management
    subgraph "Configuration Management"
        CONF("Global Config Profiles (conf/)"):::config
    end

    %% Supporting Scripts and Utilities
    subgraph "Supporting Scripts and Utilities"
        UTIL("Helper Scripts & Shared Utilities"):::support
    end

    %% Containerization & CI/CD
    subgraph "Containerization & CI/CD"
        DC("Dev Container Settings"):::ci
        CICD("CI/CD Workflows"):::ci
    end

    %% Connections from Input to Workflow Engine
    A --> M
    B --> M
    CONF --> M
    UTIL --> M
    DC --> M
    CICD --> M

    %% Workflow Engine directs to Modular Processing Units
    M --> CR1
    M --> CR2
    M --> S1
    M --> AF1
    M --> KB1
    M --> FQC
    M --> GG1
    M --> O1

    %% Internal flows within Modular Processing Units
    CR1 --> O2
    CR2 --> O2

    S1 --> O2
    S2 --> O2

    AF1 --> AF2
    AF2 --> AF3
    AF3 --> O2

    KB1 --> KB2
    KB2 --> O2

    FQC --> O2
    GG1 --> O2
    GG2 --> O2

    %% Output flows to Auxiliary Workflows
    O2 --> AW

    %% Styles
    classDef input fill:#b3cde0,stroke:#000,stroke-width:1px;
    classDef orchestrator fill:#fbb4ae,stroke:#000,stroke-width:1px;
    classDef processor fill:#ccebc5,stroke:#000,stroke-width:1px;
    classDef output fill:#ffffcc,stroke:#000,stroke-width:1px;
    classDef auxiliary fill:#d9d9d9,stroke:#000,stroke-width:1px;
    classDef config fill:#decbe4,stroke:#000,stroke-width:1px;
    classDef support fill:#f2f2f2,stroke:#000,stroke-width:1px;
    classDef ci fill:#fed9a6,stroke:#000,stroke-width:1px;

    %% Click Events
    click A "https://github.com/nf-core/scrnaseq/blob/master/assets/samplesheet.csv"
    click B "https://github.com/nf-core/scrnaseq/blob/master/modules/local/parse_cellrangermulti_samplesheet.nf"
    click M "https://github.com/nf-core/scrnaseq/blob/master/main.nf"
    click N "https://github.com/nf-core/scrnaseq/blob/master/nextflow.config"
    click CR1 "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/cellranger/count/main.nf"
    click CR2 "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/cellranger/multi/main.nf"
    click S1 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/star_align.nf"
    click S2 "https://github.com/nf-core/scrnaseq/blob/master/subworkflows/local/starsolo.nf"
    click AF1 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/simpleaf_quant.nf"
    click AF2 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/simpleaf_index.nf"
    click AF3 "https://github.com/nf-core/scrnaseq/blob/master/bin/alevin_qc.r"
    click KB1 "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/kallistobustools/count/main.nf"
    click KB2 "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/kallistobustools/ref/main.nf"
    click FQC "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/fastqc/main.nf"
    click GG1 "https://github.com/nf-core/scrnaseq/blob/master/modules/nf-core/gffread/main.nf"
    click GG2 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/gffread_transcriptome.nf"
    click O1 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/mtx_to_h5ad.nf"
    click O2 "https://github.com/nf-core/scrnaseq/blob/master/modules/local/concat_h5ad.nf"
    click AW "https://github.com/nf-core/scrnaseq/blob/master/subworkflows/local/align_cellranger.nf"
    click CONF "https://github.com/nf-core/scrnaseq/tree/master/conf/"
    click UTIL "https://github.com/nf-core/scrnaseq/blob/master/bin/generate_lib_csv.py"
    click DC "https://github.com/nf-core/scrnaseq/blob/master/.devcontainer/devcontainer.json"
    click CICD "https://github.com/nf-core/scrnaseq/blob/master/.github/workflows/ci.yml"
```
