# daehwankimlab/hisat2 architecture

> Architecture diagram of the GitHub repository daehwankimlab/hisat2, 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/daehwankimlab/hisat2
- Repository: https://github.com/daehwankimlab/hisat2

## Overview

##### Project type and purpose
- Project type: A high-performance, command-line bioinformatics tool written in C++ (with some Python, Perl, Java JNI, and website assets).
- Purpose: Build and query a Hierarchical Graph FM index (HGFM) of a reference genome (hisat2-build), then align sequencing reads (hisat2, hisat2-inspect, hisat2_repeat, etc.) against that index, producing SAM/BAM output. It also offers library bindings (Python, Java) and numerous utility scripts and evaluation pipelines.

##### File structure
Top-level directories:
- Core C++ sources and headers: aligner_*.cpp/.h, *.cpp/.h (e.g., bit_packed_array, sse_util, dp_framer, etc.), hisat2*.cpp, hisat2lib/, third_party/, threading, etc.
- Build & config: Makefile, CMakeLists.txt, msvcc/ Visual Studio projects.
- Scripts: scripts/ (Perl, shell), evaluation/ (Python-driven test suites), extract_*.py, hisat2_extract_*.py.
- Documentation & website: docs/, docs_jhu/, MANUAL.markdown, README.md, TUTORIAL.
- Example data: example/index, example/reads, example/reference.
- License, AUTHORS, NEWS, VERSION.

Architectural patterns:
- Separation of concerns (index building vs. alignment).
- Modular core “engine” (seed generation, BWT search, dynamic-programming alignment).
- Plugin/binding layers (Java JNI, Python module) in hisat2lib/.
- Scripting orchestration for evaluations and data preparation.

##### Key insights from README
- Describes two main commands: hisat2-build (indexer) and hisat2 (aligner).
- Highlights the HGFM strategy: one global GFM index + many small local GFM indexes.
- Mentions external dependencies (Python scripts for evaluation, Java JNI, Python modules).

##### Detail level
- Essential modules (seed, BWT, SW, index builder, I/O).
- Third-party/utility code as supporting blocks (tinythread, cpuid, etc.).
- Separate the pipeline into discrete steps: preprocess → index → align → postprocess/evaluate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer" 
        direction TB
        HISAT2BUILD["hisat2-build"]:::cli
        HISAT2["hisat2"]:::cli
        INSPECT["hisat2-inspect"]:::cli
        REPEAT["hisat2-repeat"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        subgraph "Indexer Module" 
            direction TB
            INDEXER["GFM Builder"]:::core
        end
        subgraph "Alignment Module"
            direction TB
            SEED["Seed Generation"]:::core
            BWT["BWT Search"]:::core
            SW["Smith-Waterman DP"]:::core
            REPORT["Result & Reporting"]:::core
        end
        subgraph "I/O Layer"
            direction TB
            IO["I/O"]:::core
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        FASTA["FASTA/FASTQ"]:::storage
        INDEXSTORE[".ht2 Index Storage"]:::storage
        SAMOUT["SAM Output"]:::storage
    end

    %% Library Bindings
    subgraph "Library Bindings" 
        direction TB
        PYTHON["Python Module"]:::bindings
        JAVA["Java JNI"]:::bindings
    end

    %% Scripts & Utilities
    subgraph "Scripts & Utilities"
        direction TB
        PREPROC["Data Preprocessors"]:::scripts
        EVAL["Evaluation Harness"]:::scripts
    end

    %% Documentation
    subgraph "Documentation & Website"
        direction TB
        JEKYLL["Jekyll Site"]:::docs
        LEGACY["Legacy Site"]:::docs
        MANUAL["Manuals & Tutorials"]:::docs
    end

    %% Build System & CI
    BUILD["Build System & CI"]:::ci

    %% Connections: Index-build workflow
    HISAT2BUILD -->|builds| INDEXER
    INDEXER -->|writes| INDEXSTORE

    %% Alignment workflow
    HISAT2 -->|reads| FASTA
    HISAT2 -->|reads| INDEXSTORE
    HISAT2 --> SEED
    SEED --> BWT
    BWT --> SW
    SW --> REPORT
    REPORT -->|writes| SAMOUT

    %% I/O integration
    INDEXER --> IO
    SEED --> IO
    BWT --> IO
    SW --> IO
    REPORT --> IO

    %% Bindings reuse core engine
    PYTHON -.-> INDEXER
    PYTHON -.-> SEED
    PYTHON -.-> BWT
    PYTHON -.-> SW
    JAVA   -.-> INDEXER
    JAVA   -.-> SEED
    JAVA   -.-> BWT
    JAVA   -.-> SW

    %% Scripts invoke CLI
    PREPROC --> HISAT2BUILD
    PREPROC --> HISAT2
    EVAL --> HISAT2BUILD
    EVAL --> HISAT2

    %% Documentation generator
    JEKYLL -->|processes| MANUAL
    LEGACY -->|processes| MANUAL

    %% Build & CI
    BUILD --> HISAT2BUILD
    BUILD --> HISAT2
    BUILD --> PYTHON
    BUILD --> JAVA

    %% Click Events
    click HISAT2BUILD "https://github.com/daehwankimlab/hisat2/tree/master/./hisat2-build"
    click HISAT2BUILD "https://github.com/daehwankimlab/hisat2/blob/master/hisat2_build.cpp"
    click HISAT2 "https://github.com/daehwankimlab/hisat2/blob/master/hisat2.cpp"
    click HISAT2 "https://github.com/daehwankimlab/hisat2/blob/master/hisat2_main.cpp"
    click INSPECT "https://github.com/daehwankimlab/hisat2/blob/master/hisat2_inspect.cpp"
    click REPEAT "https://github.com/daehwankimlab/hisat2/tree/master/./hisat2_repeat"
    click REPEAT "https://github.com/daehwankimlab/hisat2/blob/master/hisat2_repeat.cpp"
    click REPEAT "https://github.com/daehwankimlab/hisat2/blob/master/hisat2_repeat_main.cpp"
    click INDEXER "https://github.com/daehwankimlab/hisat2/blob/master/gfm.cpp"
    click INDEXER "https://github.com/daehwankimlab/hisat2/blob/master/gfm.h"
    click INDEXER "https://github.com/daehwankimlab/hisat2/blob/master/blockwise_sa.h"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed.cpp"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed.h"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed2.cpp"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed2.h"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed_policy.cpp"
    click SEED "https://github.com/daehwankimlab/hisat2/blob/master/aligner_seed_policy.h"
    click BWT "https://github.com/daehwankimlab/hisat2/blob/master/aligner_bt.cpp"
    click BWT "https://github.com/daehwankimlab/hisat2/blob/master/aligner_bt.h"
    click BWT "https://github.com/daehwankimlab/hisat2/blob/master/binary_sa_search.h"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_sw.cpp"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_sw.h"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_sw_driver.cpp"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_sw_driver.h"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_swsse.cpp"
    click SW "https://github.com/daehwankimlab/hisat2/blob/master/aligner_swsse.h"
    click REPORT "https://github.com/daehwankimlab/hisat2/blob/master/aligner_result.cpp"
    click REPORT "https://github.com/daehwankimlab/hisat2/blob/master/aligner_result.h"
    click REPORT "https://github.com/daehwankimlab/hisat2/blob/master/aligner_report.h"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/sequence_io.h"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/sam.h"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/read_qseq.cpp"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/reference.cpp"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/reference.h"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/alphabet.cpp"
    click IO "https://github.com/daehwankimlab/hisat2/blob/master/alphabet.h"
    click PYTHON "https://github.com/daehwankimlab/hisat2/blob/master/hisat2lib/pymodule/setup.py"
    click PYTHON "https://github.com/daehwankimlab/hisat2/blob/master/hisat2lib/pymodule/ht2module.c"
    click PYTHON "https://github.com/daehwankimlab/hisat2/blob/master/hisat2lib/pymodule/ht2example.py"
    click JAVA "https://github.com/daehwankimlab/hisat2/blob/master/hisat2lib/java_jni/HT2Module.java"
    click JAVA "https://github.com/daehwankimlab/hisat2/blob/master/hisat2lib/java_jni/ht2module.c"
    click PREPROC "https://github.com/daehwankimlab/hisat2/blob/master/extract_splice_sites.py"
    click PREPROC "https://github.com/daehwankimlab/hisat2/blob/master/extract_exons.py"
    click PREPROC "https://github.com/daehwankimlab/hisat2/tree/master/./scripts/"
    click EVAL "https://github.com/daehwankimlab/hisat2/tree/master/./evaluation/"
    click JEKYLL "https://github.com/daehwankimlab/hisat2/tree/master/./docs/"
    click LEGACY "https://github.com/daehwankimlab/hisat2/tree/master/./docs_jhu/"
    click MANUAL "https://github.com/daehwankimlab/hisat2/blob/master/./MANUAL.markdown"
    click MANUAL "https://github.com/daehwankimlab/hisat2/tree/master/./TUTORIAL"
    click BUILD "https://github.com/daehwankimlab/hisat2/tree/master/./Makefile"
    click BUILD "https://github.com/daehwankimlab/hisat2/blob/master/./CMakeLists.txt"
    click BUILD "https://github.com/daehwankimlab/hisat2/tree/master/./msvcc/"

    %% Styles
    classDef cli fill:#bde5b8,stroke:#2d572c
    classDef core fill:#bdd7ee,stroke:#1f497d
    classDef bindings fill:#f8cbad,stroke:#a95531,stroke-dasharray: 5 5
    classDef scripts fill:#d9d9d9,stroke:#7a7a7a
    classDef docs fill:#ffe599,stroke:#7f6000
    classDef ci fill:#c9daf8,stroke:#1155cc
    classDef storage fill:#ffffff,stroke:#000000,stroke-width:2,stroke-dasharray: 2 2
```
