# wyp1125/mcscanx architecture

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

- Interactive diagram: https://gitdiagram.com/wyp1125/mcscanx
- Repository: https://github.com/wyp1125/mcscanx

## Overview

##### Project type and purpose
- MCScanX is a command-line bioinformatics toolkit for detecting and analyzing syntenic (collinear) gene blocks across genomes.
- It consists of:
- Core C/C++ executables implementing a modified MCScan algorithm (`MCScanX`, `MCScanX_h`, `duplicate_gene_classifier`, plus helper executables like `dagchainer`, `msa`, etc.)
- A suite of downstream analysis tools in Java and Perl for plotting and further analyses.

##### File structure
- Top-level C/C++ source files and headers (`*.cc`, `*.h`), `makefile`, `cls.cc/h`, `dagchainer.cc/h`, core modules (`mcscan.cc/h`, `dup_classifier.cc/h`, etc.).
- `data/` directory holds example input files (`.blast`, `.gff`, `.tree`, `.txt`).
- `downstream_analyses/` directory with Java files (`*.java`), Perl scripts (`*.pl`), control files (`*.ctl`), and its own `makefile`.
- Configuration: root `makefile` for building native binaries, `.github/workflows/ci.yaml` for CI on GitHub.

##### README insights
- Core executables accept BLASTP output (`.blast` or `.homology`) and gene annotation (`.gff`), generate `.synteny` text files and HTML alignments.
- Downstream tools consume `.synteny`, `.gff`, control files, family/tree files, and produce plots (PNG, JPEG), enriched text outputs.
- Dependencies: Linux/Mac OS, C++ compiler, Java JDK, Perl, BLAST toolkit, BioPerl.

##### Main components
a. Build Layer
- Source Code (C++ modules, Java, Perl)
- Build Tools: GNU Make, compilers (g++, javac), CI pipeline (GitHub Actions)
b. Core CLI Executables
- MCScanX family (C++ binaries)
- duplicate_gene_classifier (C++ binary)
- Helper tools (`detect_collinear_tandem_arrays`, `dissect_multiple_alignment`, etc. in C++)
c. Downstream Analysis Tools
- Java applications (dot_plotter, dual_synteny_plotter, circle_plotter, bar_plotter, family_circle_plotter, family_tree_plotter)
- Perl scripts (add_ka_and_ks_to_synteny.pl, group_collinear_genes.pl, etc.)
d. Data Flow
- Input data: BLASTP outputs (`.blast`), homology files (`.homology`), GFF annotations, CDS FASTA, control files (`.ctl`), gene family files, tree files
- Core algorithm processing → `.synteny` files + HTML output
- Downstream tools consume `.synteny` + additional inputs → PNG/JPEG plots, text analytics
e. External Dependencies
- BLAST executables, Java runtime, Perl interpreter, BioPerl, web browser (for HTML).

##### Relationships and interactions
- The Build Layer compiles sources into native and Java binaries.
- Core executables read `.blast`/`.homology` + `.gff` → produce `.synteny` + HTML alignments.
- Downstream tools are invoked one by one (or chained in scripts/makefiles), each reading `.synteny` + control inputs → producing plots or tabular results.
- Data files can be pre-stored in `data/` or user-provided; outputs go to user-specified directories.

##### Architectural patterns and design principles
- Modular CLI pipeline: each tool focuses on a single responsibility (core synteny detection vs. specific analyses/plots).
- Separation of concerns: C++ for performance-critical algorithms, Java for visualization GUIs/plotting logic, Perl for text parsing and statistical analyses.
- Pluggable downstream modules: users can add new Perl/Java scripts that follow the same input/output conventions.
- Build/devops integration: single Makefile for native code, a downstream Makefile for additional tools, CI config for automated builds/tests.

##### Detail without over-fragmentation
- Interactions (data flows) for representative tools like `dot_plotter.java` and `add_kaks_to_synteny.pl` to illustrate the pattern.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Layer
    subgraph "Build Layer"
        Makefile["Native Makefile"]:::build
        DownMakefile["Downstream Makefile"]:::build
        CIPipeline["CI Pipeline (GitHub Actions)"]:::build
        Binaries["Compiled Binaries"]:::build
    end
    Makefile --> Binaries
    DownMakefile --> Binaries
    CIPipeline --> Binaries

    %% Data Inputs
    subgraph "Data Inputs"
        DataDir[("data/ (BLAST, .gff, .homology, .tree, .txt)")]:::data
    end

    %% Core Executables
    subgraph "C++ Core Executables"
        MCScanX["MCScanX"]:::core
        MCScanX_h["MCScanX_h"]:::core
        DupClassifier["duplicate_gene_classifier"]:::core
        CLS["cls module"]:::core
        Dagchainer["dagchainer"]:::core
        Support["Other Support Modules"]:::core
    end
    Binaries --> MCScanX
    Binaries --> MCScanX_h
    Binaries --> DupClassifier
    Binaries --> CLS
    Binaries --> Dagchainer
    Binaries --> Support

    %% Core Data Flow
    DataDir --> MCScanX
    DataDir --> MCScanX_h
    DataDir --> DupClassifier
    DataDir --> CLS
    DataDir --> Dagchainer
    MCScanX --> Synteny
    MCScanX_h --> Synteny
    DupClassifier --> Synteny
    CLS --> Synteny
    Dagchainer --> Synteny
    Support --> Synteny

    %% Synteny Output
    Synteny[(".synteny files\n+ HTML alignments")]:::data

    %% Downstream Analysis
    subgraph "Downstream Analysis"
        subgraph "Java Plotters"
            DotPlotter["dot_plotter.java"]:::java
            CirclePlotter["circle_plotter.java"]:::java
            DualPlotter["dual_synteny_plotter.java"]:::java
            BarPlotter["bar_plotter.java"]:::java
            OtherJava["Other Java Plotters"]:::java
        end
        subgraph "Perl Analytics"
            AddKaks["add_kaks_to_synteny.pl"]:::perl
            OtherPerl["Other Perl Analytics"]:::perl
        end
        subgraph "Control Files"
            DotCtl["dot.ctl"]:::data
            CircleCtl["circle.ctl"]:::data
            BarCtl["bar.ctl"]:::data
            DualCtl["dual_synteny.ctl"]:::data
            FamilyCtl["family.ctl"]:::data
        end
    end

    Synteny --> DotPlotter
    Synteny --> CirclePlotter
    Synteny --> DualPlotter
    Synteny --> BarPlotter
    Synteny --> AddKaks
    DotCtl --> DotPlotter
    CircleCtl --> CirclePlotter
    BarCtl --> BarPlotter
    DualCtl --> DualPlotter
    FamilyCtl --> OtherJava
    Synteny --> OtherJava
    Synteny --> OtherPerl

    %% External Dependencies
    subgraph "External Dependencies"
        BLAST["BLAST Toolkit"]:::external
        JavaRuntime["Java Runtime (JDK)"]:::external
        PerlInterp["Perl Interpreter\n+ BioPerl"]:::external
        Browser["Web Browser"]:::external
    end
    BLAST --> DataDir
    JavaRuntime --> DotPlotter
    PerlInterp --> AddKaks
    Browser --> Synteny

    %% Click Events
    click Makefile "https://github.com/wyp1125/mcscanx/tree/master/./makefile"
    click DownMakefile "https://github.com/wyp1125/mcscanx/tree/master/./downstream_analyses/makefile"
    click CIPipeline "https://github.com/wyp1125/mcscanx/blob/master/./.github/workflows/ci.yaml"
    click MCScanX "https://github.com/wyp1125/mcscanx/blob/master/mcscan.cc"
    click MCScanX "https://github.com/wyp1125/mcscanx/blob/master/mcscan.h"
    click MCScanX_h "https://github.com/wyp1125/mcscanx/blob/master/mcscan_h.cc"
    click MCScanX_h "https://github.com/wyp1125/mcscanx/blob/master/mcscan_h.h"
    click DupClassifier "https://github.com/wyp1125/mcscanx/blob/master/dup_classifier.cc"
    click DupClassifier "https://github.com/wyp1125/mcscanx/blob/master/dup_classifier.h"
    click CLS "https://github.com/wyp1125/mcscanx/blob/master/cls.cc"
    click CLS "https://github.com/wyp1125/mcscanx/blob/master/cls.h"
    click Dagchainer "https://github.com/wyp1125/mcscanx/blob/master/dagchainer.cc"
    click Dagchainer "https://github.com/wyp1125/mcscanx/blob/master/dagchainer.h"
    click DataDir "https://github.com/wyp1125/mcscanx/tree/master/./data/"
    click DotPlotter "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/dot_plotter.java"
    click CirclePlotter "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/circle_plotter.java"
    click DualPlotter "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/dual_synteny_plotter.java"
    click BarPlotter "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/bar_plotter.java"
    click AddKaks "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/add_kaks_to_synteny.pl"
    click DotCtl "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/dot.ctl"
    click CircleCtl "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/circle.ctl"
    click BarCtl "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/bar.ctl"
    click DualCtl "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/dual_synteny.ctl"
    click FamilyCtl "https://github.com/wyp1125/mcscanx/blob/master/./downstream_analyses/family.ctl"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef java fill:#FFA500,stroke:#333,stroke-width:1px
    classDef perl fill:#FFFF00,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
