# soedinglab/magmax architecture

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

- Interactive diagram: https://gitdiagram.com/soedinglab/magmax
- Repository: https://github.com/soedinglab/magmax

## Overview

##### Main components
- CLI Front‐end (main.rs + argument parser)
- Orchestrator / Controller (main.rs)
- Modules (each in src/*.rs):
– Merge Module (merge.rs)
– ReadFetcher Module (readfetch.rs)
– Reassemble Module (reassemble.rs)
– Quality Assessment Module (assess.rs)
– GFA Parser Module (gfaparser.rs)
– Utility library (utility.rs)
- External Tools (invoked at runtime):
– CheckM2 (quality_report.tsv)
– Skani / aligner2counts (for mapid generation)
– Seqtk (for read fetching)
– SPAdes or MEGAHIT (for reassembly)
- Data Stores (directories / files):
– Input Bins Directory (–bindir)
– MapID Directory (–mapdir)
– Reads Directory (–readdir)
– Optional Quality Report File (–qual)
– Output Bins & Reports

##### Data flow and relationships
- The Orchestrator invokes each module in sequence (or parallel where threaded):
– (Optional) Split Module if “--split” is set (within merge.rs).
– Merge Module: clusters bins by ANI/purity/completeness.
– ReadFetcher: uses mapid files + seqtk to extract relevant reads.
– Reassemble: calls SPAdes/MEGAHIT with fetched reads.
– GFA Parser (if GFA assemblies need graph‐based parsing).
– Assess: runs CheckM2 to produce or consume a quality report.

##### Architectural patterns
- Modular pipeline pattern: each stage is a self‐contained Rust module.
- Shell‐out pattern: the Reassemble and Assess modules spawn external processes.
- Threaded execution: parallelism controlled by “–threads” argument.
- Functional decomposition: utility.rs provides shared helpers.

##### Incorporate technologies & frameworks
- Rust & Cargo (runtime & build)
- Conda environment (environment.yml)
- GitHub Actions (release workflow in .github/workflows/release.yml)

##### Final checklist
[ ] Components labeled: CLI, Orchestrator, Merge, ReadFetcher, Reassemble, GFAParser, Assess, Utility
[ ] Data stores labeled: binsdir, mapdir, readdir, quality_report, output
[ ] External tools: CheckM2, skani/aligner2counts, seqtk, SPAdes, MEGAHIT

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Rust Modules"
        CLI["CLI Front-end"]:::internal
        Orch["Orchestrator / Controller"]:::internal
        Merge["Merge Module"]:::internal
        ReadFetch["ReadFetcher Module"]:::internal
        Reassemble["Reassemble Module"]:::internal
        GFA["GFA Parser Module"]:::internal
        Assess["Quality Assessment Module"]:::internal
        Utility["Utility Library"]:::internal
    end

    subgraph "Data Stores"
        bins["binsdir (–bindir)"]:::data
        mapids["mapdir (–mapdir)"]:::data
        reads["readdir (–readdir)"]:::data
        qual["quality_report.tsv (–qual)"]:::data
        output["Output Bins & Reports"]:::data
    end

    subgraph "External Tools"
        CheckM2["CheckM2"]:::external
        Skani["skani/aligner2counts"]:::external
        Seqtk["Seqtk"]:::external
        SPAdes["SPAdes"]:::external
        MegaHIT["MEGAHIT"]:::external
    end

    subgraph "Configuration & CI"
        Cargo["Cargo.toml"]:::config
        Conda["environment.yml"]:::config
        GH[".github/workflows/release.yml"]:::config
    end

    %% Data and Control Flow
    CLI -->|"parses args"| Orch
    Orch -->|"invokes"| Merge
    bins -->|"bins.fasta"| Merge
    Merge -->|"merged_bins.fasta"| output

    Orch -->|"invokes"| ReadFetch
    mapids -->|"mapid files"| ReadFetch
    Seqtk -->|"shell out"| ReadFetch
    ReadFetch -->|"fetched_reads.fastq"| readdir
    reads -->|"reads input"| Reassemble

    Orch -->|"invokes"| Reassemble
    Reassemble -->|"assembly output"| output
    Reassemble -->|"shell out"| SPAdes
    Reassemble -->|"shell out"| MegaHIT

    Orch -->|"invokes"| GFA
    GFA -->|"parsed graphs"| output

    Orch -->|"invokes"| Assess
    Assess -->|"consumes/produces"| qual
    Assess -->|"shell out"| CheckM2

    %% Utility usage
    Utility -.-> Merge
    Utility -.-> ReadFetch
    Utility -.-> Reassemble
    Utility -.-> GFA
    Utility -.-> Assess

    %% Configuration dependencies
    Cargo -.-> CLI
    Cargo -.-> Utility
    Conda -.-> CLI
    GH -.-> CLI

    %% Click Events
    click CLI "https://github.com/soedinglab/magmax/blob/main/src/main.rs"
    click Merge "https://github.com/soedinglab/magmax/blob/main/src/merge.rs"
    click ReadFetch "https://github.com/soedinglab/magmax/blob/main/src/readfetch.rs"
    click Reassemble "https://github.com/soedinglab/magmax/blob/main/src/reassemble.rs"
    click GFA "https://github.com/soedinglab/magmax/blob/main/src/gfaparser.rs"
    click Assess "https://github.com/soedinglab/magmax/blob/main/src/assess.rs"
    click Utility "https://github.com/soedinglab/magmax/blob/main/src/utility.rs"
    click Cargo "https://github.com/soedinglab/magmax/blob/main/Cargo.toml"
    click Conda "https://github.com/soedinglab/magmax/blob/main/environment.yml"
    click GH "https://github.com/soedinglab/magmax/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#0366d6,stroke-width:2px
    classDef external fill:#FFD8A8,stroke:#d66108,stroke-width:2px,stroke-dasharray: 5 5
    classDef data fill:#D0F0C0,stroke:#228B22,stroke-width:2px
    classDef config fill:#E2E2E2,stroke:#6a737d,stroke-width:2px,stroke-dasharray: 3 3
```
