# arkadiy-garber/mhcscan architecture

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

- Interactive diagram: https://gitdiagram.com/arkadiy-garber/mhcscan
- Repository: https://github.com/arkadiy-garber/mhcscan

## Overview

##### Project type and purpose
- MHCscan is an open-source, command-line bioinformatics pipeline for identifying multiheme cytochromes in either predicted proteomes or raw genomic contigs.
- It is not a web app or microservices suite, but a sequential CLI tool that orchestrates several binaries and scripts.

##### File structure
- Top-level:
- LICENSE, README.md, setup.sh
- bin/ (all executables and scripts)
- bin/:
- MHCscan.sh – the main orchestrator shell script
- decodeanhmm(.64bit) – compiled binary for HMM decoding
- mhc_annotate.py – Python aggregator for final annotation
- phobius.pl, phobius.model, phobius.options – for transmembrane prediction
- remove_asterisk.py – small helper
- Implied external dependencies (from README): Prodigal, HHSuite, hh-suite databases (e.g., PDB70)

##### Review the README for pipeline steps
- Input: proteins.faa + annotation.gff (–prot) or contigs.fasta
- Gene calling (if needed): Prodigal
- HMM searches: HHblits/HHsearch against PDB70
- TM prediction: Phobius
- HMM decoding: decodeanhmm
- Final annotation & CSV output: mhc_annotate.py

##### Main components and their interactions
a. Input layer
– User supplies FASTA (.faa or .fasta) and optionally GFF.
b. Orchestration module
– MHCscan.sh parses flags, sets up temp dirs, invokes each tool in sequence.
c. Gene‐calling
– Prodigal (external binary) turns contigs into proteins + GFF.
d. HMM scanning
e. Transmembrane prediction
– Phobius (internal Perl script + models).
f. HMM decoding
– decodeanhmm binary applies internal logic to HMM outputs.
g. Aggregation & output
– mhc_annotate.py collects all partial results, produces output.csv.
h. Configuration & environment
– setup.sh, Conda environment manages dependencies.

##### Architectural patterns and principles
- Pipeline pattern: linear, stepwise processing.
- Single-responsibility: each tool does one analysis step.
- Modularity: bin/ directory clearly separates tooling from orchestration.
- Reproducibility: Conda environment boundaries shown as context.

- A zoomed-in inset (or separate page) showing the internal calls within MHCscan.sh (tool order, key flags).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Environment Setup
    subgraph "Environment Setup"
        Env["Conda Environment<br/>(setup.sh)"]:::orchestrator
    end

    %% Input Layer
    subgraph "Input"
        FASTA["proteins.faa<br/>(or contigs.fasta)"]:::input
        GFF["annotation.gff"]:::input
    end

    %% Decision in orchestrator
    MHC["MHCscan.sh<br/>(Orchestrator)"]:::orchestrator
    click MHC "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/MHCscan.sh"

    %% Gene Calling
    Prodigal["Prodigal (external)"]:::external

    %% HMM Scanning
    HH["HHblits/HHsearch (HHSuite)"]:::external
    PDB["PDB70 Database"]:::database

    %% Transmembrane Prediction
    Phobius["Phobius<br/>(pl, model, options)"]:::external
    click Phobius "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/phobius.pl"
    click Phobius "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/phobius.model"
    click Phobius "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/phobius.options"

    %% HMM Decoding
    Decode["decodeanhmm<br/>(binary)"]:::internal
    click Decode "https://github.com/arkadiy-garber/mhcscan/tree/main/bin/decodeanhmm"
    click Decode "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/decodeanhmm.64bit"

    %% Helper Script
    Remove["remove_asterisk.py"]:::internal
    click Remove "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/remove_asterisk.py"

    %% Aggregation & Output
    Annotate["mhc_annotate.py"]:::internal
    click Annotate "https://github.com/arkadiy-garber/mhcscan/blob/main/bin/mhc_annotate.py"
    Output["output.csv"]:::input

    %% Flow
    FASTA -->|"-prot / -i"| MHC
    GFF -->|optional| MHC
    MHC -->|"if contigs.fasta"| Prodigal
    Prodigal -->|"proteins.faa + GFF"| MHC
    MHC -->|"FAA → HMM" | HH
    HH -->|".hmm" | Decode
    HH -->|uses| PDB
    MHC -->|"FAA → Phobius"| Phobius
    Phobius -->|TM predictions| Decode
    Decode -->|decoded hits| Remove
    Remove -->|cleaned seqs| Annotate
    Annotate -->|aggregates| Output

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1F618D
    classDef external fill:#FADBD8,stroke:#C0392B
    classDef database fill:#D5F5E3,stroke:#27AE60
    classDef input fill:#FCF3CF,stroke:#B7950B
    classDef orchestrator fill:#E8DAEF,stroke:#76448A
```
