# twolinin/longphase architecture

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

- Interactive diagram: https://gitdiagram.com/twolinin/longphase
- Repository: https://github.com/twolinin/longphase

## Overview

##### Main components
- User/CLI Interface – this is where users interact with the tool via different subcommands (phase, haplotag, modcall).
- Command Argument Parser and Main Entry (main.cpp) – routing inputs to the correct module based on user parameters.
- Core Modules:
– Phasing Module: Contains files like Phasing.cpp, PhasingGraph.cpp, and PhasingProcess.cpp. This component handles building the variant graph, applying phasing algorithms, and processing SNPs, indels, and SVs.
– Haplotag Module: Implemented in files such as Haplotag.cpp and HaplotagProcess.cpp. It assigns haplotype tags to reads in BAM files and coordinates with phased VCF outputs.
– ModCall Module: With ModCall.cpp and ModCallProcess.cpp. It extracts allele-specific modifications from the BAM (using MM/ML tags) and outputs modification VCFs.
– Utility Components: Util.cpp provides common utility functions that support all modules.
- External Library Interface:
– htslib integration: The project includes an entire subdirectory of htslib. This library is used for reading/writing BAM, VCF, and FASTA files, and for other I/O operations.
– jemalloc dependency: Included as a subdirectory; used to optimize dynamic memory allocation.
- Build and Configuration Layer:
– Autotools (configure.ac, config.mk.in) and Makefile support.
– Dockerfile for containerization.

##### Relationships and interactions
- The user issues a command via the CLI → the main executable (from main.cpp) uses a command-line parser to determine which subcommand to run.
- Depending on the subcommand (phase, haplotag, modcall), control flows to the corresponding module.
– In the Phase module, inputs include VCF (SNP/indels/SV/modification), FASTA (reference genome), and one or more BAM files. These are processed by a pipeline that:
– Reads data via htslib routines,
– Constructs a phasing graph (using PhasingGraph.cpp),
– Applies edge weight adjustments based on base quality (parameters set in Phasing.cpp), and finally
– Writes out phased VCFs.
– In the Haplotag module, the phased VCF output (from phase) and BAM files are re-read (again via htslib) to assign haplotype tags to each read.
– The ModCall module receives BAM input with modification tags and uses similar parsing routines to output a VCF representing allele-specific modifications.
- The utility functions (from Util.cpp) are shared across modules to support logging, error handling, and data conversions.

##### Architectural patterns and design principles
- Modular design: Each functional command (phase, haplotag, modcall) is implemented as a separate module with its own processing pipeline. This separation allows for maintainability and independent improvements.
- Layered architecture: The system separates the data input/IO (handled via htslib), the processing/algorithm layers (phasing graph construction, haplotagging, modification calling), and the output (VCF/BAM file generation).
- Integration of external dependencies: The design clearly encapsulates the htslib library (and also jemalloc) as external components that provide essential low-level functionality.
- Command-line driven and parameterizable: The design is highly configurable via command-line options (as shown in the README) which drives modules’ behavior.

##### Additional notes
- Given the project’s pipeline nature, illustrate the sequential flow from data ingestion (reading BAM, VCF, FASTA) through algorithmic processing and then output generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    User["User/CLI"]:::input
    Main["Command Parser & Main Controller"]:::controller
    Utility["Utility Components"]:::utility

    %% External Libraries
    subgraph "External Libraries"
        HTSLIB["htslib"]:::external
        JEMALLOC["jemalloc"]:::external
    end

    %% Build and Configuration
    subgraph "Build/Configuration"
        AT["Autotools"]:::build
        DF["Dockerfile"]:::build
    end

    %% User flow
    User -->|"issuesCommand"| Main

    %% Main modules connection:
    Main -->|"phase"| PG_PhaseGraph
    Main -->|"haplotag"| HR_HaplotagTagger
    Main -->|"modcall"| MC_ModCallDetect

    %% Phasing Module Subgraph
    subgraph "Phasing Module"
        direction TB
        PG_PhaseGraph["Variant Graph Construction"]:::module
        PC_PhaseCore["Phasing Core Logic"]:::module
        PP_PhaseProc["Phasing Process"]:::module
        IO_PhaseIO["Input/Output Handler (htslib)"]:::module
        PG_PhaseGraph --> PC_PhaseCore
        PC_PhaseCore --> PP_PhaseProc
        PP_PhaseProc --> IO_PhaseIO
    end

    %% Haplotag Module Subgraph
    subgraph "Haplotag Module"
        direction TB
        HR_HaplotagTagger["Haplotag Read Tagger"]:::module
        HL_HaplotagLookup["Variant Lookup"]:::module
        HR_HaplotagTagger --> HL_HaplotagLookup
    end

    %% ModCall Module Subgraph
    subgraph "ModCall Module"
        direction TB
        MC_ModCallDetect["Modification Detection"]:::module
        MP_ModCallProcess["ModCall Processing"]:::module
        MPB_BamParsing["BAM Parsing"]:::module
        VCF_ModCallVCF["VCF Generation"]:::module
        MC_ModCallDetect --> MP_ModCallProcess
        MP_ModCallProcess --> MPB_BamParsing
        MPB_BamParsing --> VCF_ModCallVCF
    end

    %% Dependencies on Utility
    IO_PhaseIO -->|"utilCalls"| Utility
    HL_HaplotagLookup -->|"utilCalls"| Utility
    VCF_ModCallVCF -->|"utilCalls"| Utility

    %% Dependencies on External Libraries
    IO_PhaseIO ---|"uses"| HTSLIB
    HR_HaplotagTagger ---|"reads/writes"| HTSLIB
    VCF_ModCallVCF ---|"reads/writes"| HTSLIB
    PC_PhaseCore ---|"memoryOpt"| JEMALLOC

    %% Build and Configuration dependency to Main Controller
    AT ---|"buildTool"| Main
    DF ---|"containerBuild"| Main

    %% Styles
    classDef input fill:#C1E1C1,stroke:#2F7D32,stroke-width:2px;
    classDef controller fill:#FFEDB6,stroke:#C68E17,stroke-width:2px;
    classDef module fill:#B2D7FF,stroke:#2176C7,stroke-width:2px;
    classDef utility fill:#FFE699,stroke:#B8860B,stroke-width:2px;
    classDef external fill:#FFD1DC,stroke:#D33F6A,stroke-width:2px;
    classDef build fill:#D1E8FF,stroke:#1F77B4,stroke-width:2px;

    %% Click Events for Component Mappings
    click Main "https://github.com/twolinin/longphase/blob/main/main.cpp"
    click PG_PhaseGraph "https://github.com/twolinin/longphase/blob/main/PhasingGraph.cpp"
    click PC_PhaseCore "https://github.com/twolinin/longphase/blob/main/Phasing.cpp"
    click PP_PhaseProc "https://github.com/twolinin/longphase/blob/main/PhasingProcess.cpp"
    click HR_HaplotagTagger "https://github.com/twolinin/longphase/blob/main/Haplotag.cpp"
    click HL_HaplotagLookup "https://github.com/twolinin/longphase/blob/main/HaplotagProcess.cpp"
    click MC_ModCallDetect "https://github.com/twolinin/longphase/blob/main/ModCall.cpp"
    click MP_ModCallProcess "https://github.com/twolinin/longphase/blob/main/ModCallProcess.cpp"
    click MPB_BamParsing "https://github.com/twolinin/longphase/blob/main/ModCallParsingBam.cpp"
    click Utility "https://github.com/twolinin/longphase/blob/main/Util.cpp"
    click HTSLIB "https://github.com/twolinin/longphase/tree/main/htslib"
    click JEMALLOC "https://github.com/twolinin/longphase/tree/main/jemalloc"
    click AT "https://github.com/twolinin/longphase/blob/main/configure.ac"
    click AT "https://github.com/twolinin/longphase/blob/main/config.mk.in"
    click AT "https://github.com/twolinin/longphase/tree/main/Makefile"
    click DF "https://github.com/twolinin/longphase/tree/main/Dockerfile"
```
