# alesanzdro/epibac architecture

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

- Interactive diagram: https://gitdiagram.com/alesanzdro/epibac
- Repository: https://github.com/alesanzdro/epibac

## Overview

##### Main Components
- Environment Setup and Package Management: Represent the use of Conda and Mamba for environment management. Show the “base” environment (for mamba and conda configuration) and the dedicated “snake” environment for Snakemake execution.
- Input Data/External Resources: Include components for:
- Raw input files (FASTQ files and samples_info/samplesheet in the “test” and “RAWDATA” directories).
- Configuration and schema files (config.yaml, schemas directory) that govern pipeline behavior and input validation.
- Snakemake Workflow Engine: This is the core orchestrator of the pipeline. Represent the workflow as:
- A block for the Snakemake engine.
- Subcomponents that correspond to the individual rule files located in the “rules” directory (such as assembly.smk, qc.smk, annotation.smk, report.smk, setup.smk, and amr_mlst.smk). Each rule represents a processing step, and collectively they form the Directed Acyclic Graph (DAG) of the pipeline.
- Supporting Scripts & Utilities: Include the “scripts” directory, which has helper programs for generating a samplesheet and validating the sample information.
- Testing and Validation: A component showing the test data as exemplified in the “test” folder, used for both pipeline’s execution validation and demonstration (including example outputs, like report.html and dag.png).

##### Relationships and Data Flow
- That the outputs of these rules are aggregated into a final report (as illustrated by the report.smk rule and eventual Excel outputs), and there’s also a separate report format for hospital-specific “GVA” needs.

##### Architectural Patterns and Key Technologies
- Use of a workflow engine (Snakemake) which inherently supports modularization and parallel execution.
- Reproducibility provided by the use of conda environments (with environment YAML files in the “envs” directory).
- Extent to which the pipeline adheres to common bioinformatics practices: separation of configuration (config.yaml, schemas), rule-based processing (rules/*.smk), and container-like environment reproducibility.
- External services like Git for version control (note the .gitignore and authors.md).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Setup
    subgraph "Environment Setup"
        ENV["Conda Environment Setup"]:::env
    end

    %% Input Data & External Resources
    subgraph "Input Data & External Resources"
        RI["Raw Input Files"]:::input
        SM["Sample Metadata"]:::input
        subgraph "Configuration & Schemas"
            CS["config.yaml"]:::input
            SC["Schemas Directory"]:::input
        end
    end

    %% Supporting Scripts & Utilities
    subgraph "Supporting Scripts & Utilities"
        DS["Samplesheet Generation (do_samplesheet.py)"]:::script
        VS["Validation (validate_samples_info.py)"]:::script
        ES["Summary Utility (epibac_summary.py)"]:::script
    end

    %% Snakemake Workflow Engine
    subgraph "Snakemake Workflow Engine"
        SE["Central Orchestrator (Snakefile)"]:::engine
        subgraph "Snakemake Rules"
            RSetup["Setup Rule (setup.smk)"]:::rule
            RQC["QC Rule (qc.smk)"]:::rule
            RAssembly["Assembly Rule (assembly.smk)"]:::rule
            RAnnotation["Annotation Rule (annotation.smk)"]:::rule
            RReport["Report Rule (report.smk)"]:::rule
            RAMLST["AMR/MLST Rule (amr_mlst.smk)"]:::rule
            RCommon["Common Rules (common.smk)"]:::rule
        end
    end

    %% Output Results
    subgraph "Output Results"
        OR["Final Reports & Outputs (report.html, etc.)"]:::output
    end

    %% Testing and Validation
    subgraph "Testing and Validation"
        TEST["Test Data & Pipeline Outputs"]:::test
    end

    %% Version Control & Documentation
    subgraph "Version Control & Documentation"
        VC["Version Control & Docs"]:::vc
        GIG["Gitignore (.gitignore)"]:::vc
        AD["Authors (authors.md)"]:::vc
    end

    %% Data Flow Connections
    ENV -->|"sets up environments"| RI
    ENV -->|"sets up environments"| SM
    RI -->|"provides FASTQ reads"| DS
    SM -->|"provides metadata"| DS
    SM -->|"validated by"| VS
    CS -->|"configures"| SE
    DS -->|"pre-processed data"| SE
    VS -->|"ensures integrity"| SE
    ES -->|"supplements analysis"| SE

    SE -->|"initializes"| RSetup
    SE -->|"utilizes"| RCommon
    RSetup -->|"installs dependencies"| RQC
    RQC -->|"processes quality control"| RAssembly
    RAssembly -->|"assembles genomes"| RAnnotation
    RAnnotation -->|"generates analysis"| RReport
    RAnnotation -->|"performs AMR/MLST"| RAMLST
    RReport -->|"aggregates results"| OR
    RAMLST -->|"aggregates results"| OR
    OR -->|"validated by"| TEST

    %% Version Control Connections (informational)
    VC ---|"tracks changes"| ENV
    VC --- GIG
    VC --- AD

    %% Click Events
    click ENV "https://github.com/alesanzdro/epibac/tree/main/envs/"
    click RI "https://github.com/alesanzdro/epibac/tree/main/test/raw_data/"
    click SM "https://github.com/alesanzdro/epibac/blob/main/test/samples_info.csv"
    click CS "https://github.com/alesanzdro/epibac/blob/main/config.yaml"
    click SC "https://github.com/alesanzdro/epibac/tree/main/schemas/"
    click DS "https://github.com/alesanzdro/epibac/blob/main/scripts/do_samplesheet.py"
    click VS "https://github.com/alesanzdro/epibac/blob/main/scripts/validate_samples_info.py"
    click ES "https://github.com/alesanzdro/epibac/blob/main/scripts/epibac_summary.py"
    click SE "https://github.com/alesanzdro/epibac/tree/main/Snakefile"
    click RSetup "https://github.com/alesanzdro/epibac/blob/main/rules/setup.smk"
    click RQC "https://github.com/alesanzdro/epibac/blob/main/rules/qc.smk"
    click RAssembly "https://github.com/alesanzdro/epibac/blob/main/rules/assembly.smk"
    click RAnnotation "https://github.com/alesanzdro/epibac/blob/main/rules/annotation.smk"
    click RReport "https://github.com/alesanzdro/epibac/blob/main/rules/report.smk"
    click RAMLST "https://github.com/alesanzdro/epibac/blob/main/rules/amr_mlst.smk"
    click RCommon "https://github.com/alesanzdro/epibac/blob/main/rules/common.smk"
    click TEST "https://github.com/alesanzdro/epibac/tree/main/test/"
    click GIG "https://github.com/alesanzdro/epibac/blob/main/.gitignore"
    click AD "https://github.com/alesanzdro/epibac/blob/main/authors.md"

    %% Styles
    classDef env fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef input fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef script fill:#fad7a0,stroke:#f39c12,stroke-width:2px;
    classDef engine fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef rule fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef output fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
    classDef test fill:#d5f5e3,stroke:#2ecc71,stroke-width:2px;
    classDef vc fill:#d6eaf8,stroke:#5dade2,stroke-width:2px;
```
