# jhhlab/biovoltron architecture

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

- Interactive diagram: https://gitdiagram.com/jhhlab/biovoltron
- Repository: https://github.com/jhhlab/biovoltron

## Overview

##### Project type and purpose
- This is a C++ bioinformatics library (“biovoltron”) that provides:
- File‐I/O for FASTA/FASTQ formats
- In‐memory container types (bit vectors)
- Core algorithms (e.g., suffix sorting)
- Utility routines (string handling, logging)
- It is delivered as a modular library built with CMake, with submodules for third-party dependencies, tested via Catch2, and documented via Doxygen.

##### File structure
- Top-level:
- CMakeLists.txt – orchestrates build of library, tests, docs
- /biovoltron – public headers organized into algo, container, file_io, utility
- submodules – git submodules for boost-cmake, bzip2, doxygen-css, htslib, libsimdpp, range-v3, spdlog, tbb
- tests – unit tests organized in parallel to modules
- docs – Doxygen config and markdown tutorials
- .github/workflows – CI definitions for build, test, deploy

##### README (docs/markdown/index.md)
- Likely outlines installation, usage examples (file I/O tutorials, algorithm demos) and links to generated API docs.
- May call out supported file formats and core performance features (SIMD, TBB parallelism).

a. Core Library Modules:
- file_io (FASTA/FASTQ Reader/Writer)
- container (xbit_vector, dibit_vector)
- algo (suffix_sorter: core & stable_sorter)
- utility (istring, logging facade)
b. External Dependencies (submodules):
- build support: boost-cmake
- compression: bzip2
- I/O helpers: htslib
- parallelism: TBB
- algorithm support: libsimdpp, range-v3
- logging: spdlog
- docs styling: doxygen-awesome-css
c. Build & CI:
- CMake → library + tests + docs
- GitHub Actions workflows (pull-request-check + deploy)
d. Documentation:
- Doxygen pipeline (Doxyfile, custom CSS, header, layout)
- markdown tutorials

##### Relationships and interactions
- Input FASTA/FASTQ files → file_io core → record tuples
- Records → container types → fed into algo::suffix_sorter → sorted indices/results
- Utility functions (istring) support parsing; logging via spdlog throughout
- Build system (CMake) pulls in submodules, compiles core + tests, generates docs
- CI triggers CMake, runs tests, builds & publishes docs

##### Architectural patterns & principles
- Modular layering: I/O → data structures → algorithms → utilities
- Single Responsibility: each module has a focused role
- Dependency Injection via template headers (no global state)
- Extensibility: submodule-based plugin-style dependency management

##### Essential elements
- Clear labels for each module and submodule
- On tooling: CMake, GitHub Actions, Doxygen

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core Modules"
        direction TB
        fileio["file_io"]:::core
        subgraph "file_io Submodules"
            direction TB
            fio_core_headers["core headers"]:::core
            fio_fasta["fasta"]:::core
            fio_fastq["fastq"]:::core
        end
        container["container"]:::core
        subgraph "container Submodules"
            direction TB
            cont_all["all.hpp"]:::core
            cont_xbit["xbit_vector.hpp"]:::core
        end
        algo["algo"]:::core
        subgraph "algo Submodules"
            direction TB
            algo_all["all.hpp"]:::core
            ss_all["suffix_sorter all.hpp"]:::core
            ss_core["suffix_sorter core"]:::core
            ss_stable["stable_sorter.hpp"]:::core
        end
        utility["utility"]:::core
        subgraph "utility Submodules"
            direction TB
            util_all["all.hpp"]:::core
            util_istring["istring.hpp"]:::core
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ext_boost["boost-cmake"]:::ext
        ext_bzip2["bzip2"]:::ext
        ext_doxycss["doxygen-awesome-css"]:::ext
        ext_htslib["htslib"]:::ext
        ext_simdpp["libsimdpp"]:::ext
        ext_range["range-v3"]:::ext
        ext_spdlog["spdlog"]:::ext
        ext_tbb["TBB"]:::ext
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        cmake_root["CMakeLists.txt"]:::build
        cmake_docs["docs/CMakeLists.txt"]:::build
        gha_pr["pull-request-check.yml"]:::build
        gha_deploy["deploy.yml"]:::build
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        doxy_config["Doxyfile & Layout"]:::docs
        doxy_style["custom.css & header.html"]:::docs
        md_tutorials["Markdown Tutorials"]:::docs
    end

    %% Tests
    subgraph "Unit Tests"
        direction TB
        test_fasta["tests/file_io/fasta.cpp"]:::core
        test_fastq["tests/file_io/fastq.cpp"]:::core
        test_dibit["tests/container/dibit_vector.cpp"]:::core
        test_ss_core["tests/algo/suffix_sorter/core/suffix_sorter.cpp"]:::core
        test_ss_stable["tests/algo/suffix_sorter/stable_sorter.cpp"]:::core
        test_istring["tests/utility/istring.cpp"]:::core
    end

    %% Data Flow
    fileio -->|"reads →"| container
    container -->|"feeds →"| algo
    utility -->|"parses/logs →"| fileio
    utility -->|"parses/logs →"| algo

    %% Build Dependencies
    cmake_root -->|pulls| ext_boost
    cmake_root -->|pulls| ext_bzip2
    cmake_root -->|pulls| ext_doxycss
    cmake_root -->|pulls| ext_htslib
    cmake_root -->|pulls| ext_simdpp
    cmake_root -->|pulls| ext_range
    cmake_root -->|pulls| ext_spdlog
    cmake_root -->|pulls| ext_tbb
    cmake_root -->|builds| fileio
    cmake_root -->|builds| container
    cmake_root -->|builds| algo
    cmake_root -->|builds| utility
    cmake_root -->|generates| cmake_docs

    %% CI Triggers
    gha_pr -->|triggers| cmake_root
    gha_pr -->|runs| test_fasta
    gha_pr -->|runs| test_fastq
    gha_pr -->|runs| test_dibit
    gha_pr -->|runs| test_ss_core
    gha_pr -->|runs| test_ss_stable
    gha_pr -->|runs| test_istring
    gha_pr -->|builds| docs

    gha_deploy -->|publishes| docs

    %% Documentation Pipeline
    cmake_docs -->|uses| doxy_config
    cmake_docs -->|uses| doxy_style
    cmake_docs -->|includes| md_tutorials

    %% Tests Depend on Modules
    test_fasta -->|tests| fio_fasta
    test_fastq -->|tests| fio_fastq
    test_dibit -->|tests| cont_xbit
    test_ss_core -->|tests| ss_core
    test_ss_stable -->|tests| ss_stable
    test_istring -->|tests| util_istring

    %% Click Events
    click fileio "https://github.com/jhhlab/biovoltron/tree/master/include/biovoltron/file_io"
    click fio_core_headers "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/file_io/core/header.hpp"
    click fio_fasta "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/file_io/fasta.hpp"
    click fio_fastq "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/file_io/fastq.hpp"
    click test_fasta "https://github.com/jhhlab/biovoltron/blob/master/tests/file_io/fasta.cpp"
    click test_fastq "https://github.com/jhhlab/biovoltron/blob/master/tests/file_io/fastq.cpp"

    click cont_all "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/container/all.hpp"
    click cont_xbit "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/container/xbit_vector.hpp"
    click test_dibit "https://github.com/jhhlab/biovoltron/blob/master/tests/container/dibit_vector.cpp"

    click algo_all "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/algo/all.hpp"
    click ss_all "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/algo/suffix_sorter/all.hpp"
    click ss_core "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/algo/suffix_sorter/core/suffix_sorter.hpp"
    click ss_stable "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/algo/suffix_sorter/stable_sorter.hpp"
    click test_ss_core "https://github.com/jhhlab/biovoltron/blob/master/tests/algo/suffix_sorter/core/suffix_sorter.cpp"
    click test_ss_stable "https://github.com/jhhlab/biovoltron/blob/master/tests/algo/suffix_sorter/stable_sorter.cpp"

    click util_all "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/utility/all.hpp"
    click util_istring "https://github.com/jhhlab/biovoltron/blob/master/include/biovoltron/utility/istring.hpp"
    click test_istring "https://github.com/jhhlab/biovoltron/blob/master/tests/utility/istring.cpp"

    click cmake_root "https://github.com/jhhlab/biovoltron/blob/master/CMakeLists.txt"
    click cmake_docs "https://github.com/jhhlab/biovoltron/blob/master/docs/CMakeLists.txt"
    click gha_pr "https://github.com/jhhlab/biovoltron/blob/master/.github/workflows/pull-request-check.yml"
    click gha_deploy "https://github.com/jhhlab/biovoltron/blob/master/.github/workflows/deploy.yml"

    click doxy_config "https://github.com/jhhlab/biovoltron/blob/master/docs/Doxyfile.in"
    click doxy_style "https://github.com/jhhlab/biovoltron/blob/master/docs/custom.css"
    click md_tutorials "https://github.com/jhhlab/biovoltron/blob/master/docs/markdown/index.md"

    click ext_boost "https://github.com/jhhlab/biovoltron/tree/master/submodules/boost-cmake"
    click ext_bzip2 "https://github.com/jhhlab/biovoltron/tree/master/submodules/bzip2"
    click ext_doxycss "https://github.com/jhhlab/biovoltron/tree/master/submodules/doxygen-awesome-css"
    click ext_htslib "https://github.com/jhhlab/biovoltron/tree/master/submodules/htslib"
    click ext_simdpp "https://github.com/jhhlab/biovoltron/tree/master/submodules/libsimdpp"
    click ext_range "https://github.com/jhhlab/biovoltron/tree/master/submodules/range-v3"
    click ext_spdlog "https://github.com/jhhlab/biovoltron/tree/master/submodules/spdlog"
    click ext_tbb "https://github.com/jhhlab/biovoltron/tree/master/submodules/tbb"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#2196F3,stroke-width:2px
    classDef ext fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef build fill:#E0E0E0,stroke:#757575,stroke-width:2px
    classDef docs fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px
```
