# kojix2/ruby-htslib architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/ruby-htslib
- Repository: https://github.com/kojix2/ruby-htslib

## Overview

##### Project Type and Purpose
- This project is a language binding library – a “glue” layer between Ruby and the underlying C library (HTSlib).
- Its purpose is to offer Ruby developers a high-level API (in modules like HTS::Bam, HTS::Bcf, etc.) to interact with common bioinformatics file formats by internally calling native C functions via Ruby-FFI.

##### File Structure
- Top-level Directories & Files:
- “lib/hts”: Contains the core Ruby modules and classes for different genomic file formats. Notice subdirectories for BAM (including auxiliary files, header, flag, record, etc.), BCF, FAIDX, and Tabix; this indicates modularization according to each file format.
- “lib/hts/ffi_ext”: A dedicated directory for low-level FFI extensions, dealing with pointers, structs, and integration with the native library.
- “lib/hts/libhts”: Contains bindings to the native HTSlib functions, constants, and thread pool — essentially the low-level API enabling direct communication with HTSlib.
- “examples” and “test”: Provide scripts and tests demonstrating how the API is used (e.g., reading/writing genomic files) and ensuring correctness.
- “scripts”: Contains tools (such as c2ffi, func2rb.rb, struct2rb.rb) to generate or validate FFI bindings and to assist in keeping the Ruby-side implementations in sync with HTSlib changes.
- Other items like Dockerfile, GitHub workflows, and build configuration files indicate continuous integration and packaging processes.

##### Components
a. High-Level Ruby API Layer:
- Components such as HTS::Bam, HTS::Bcf, HTS::Faidx, and HTS::Tabix that provide an object-oriented interface for genomic data.
- These classes contain methods that perform tasks like opening files, iterating over records, and providing a developer-friendly interface.

b. Low-Level FFI Binding Layer:
- The LibHTS module in “lib/hts/libhts” that directly maps to HTSlib functions using Ruby-FFI.
- Any helper modules in “lib/hts/ffi_ext” that manage memory and pointer structures.
- Re-implementation of C macros into Ruby (as referenced in the README) to bypass Ruby-FFI limitations.

c. Native HTSlib Component:
- Although not a separate submodule in this repository, HTSlib (the underlying C library) is a key external dependency. Indicate that calls from LibHTS interface directly with the native library.

d. Supporting Tools and Development Infrastructure:
- The “scripts” directory providing tooling for converting C headers to Ruby ffi bindings (c2ffi, etc.).
- The “test” and “examples” directories which, while not part of production execution, illustrate how the API components interoperate and are validated.
- Build and continuous integration files (Dockerfile, GitHub workflows) that show how code is compiled, tests are run, and how integration with HTSlib is maintained.

##### Relationships and Interactions
- A Ruby application (or test/example script) calls a high-level API method (e.g., HTS::Bam.open).
- The high-level API delegates functionality to lower-level helper methods, which, via Ruby-FFI, invoke the corresponding C functions wrapped in the LibHTS module.
- These calls communicate with HTSlib (native C library) to perform the required operations (file reading, writing, etc.).
- Data (like BAM records or VCF fields) returned from HTSlib are processed via FFI bindings and then re-packaged into Ruby objects.
- Memory management should be highlighted, particularly where ManagedStruct and FFI::Struct are used to automatically (or sometimes manually) free memory.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separation between the high-level Ruby API and the low-level FFI bindings.
- Modularity: Each file format (BAM, BCF, etc.) is implemented in its own set of modules, making it easier to extend or modify features independently.
- Interoperability: Emphasis on bridging Ruby and C through FFI. The reimplementation of C macros in Ruby and memory management differences (GC on Ruby vs. manual release) are critical details.
- Testing and Continuous Integration: Emphasize that tests, examples, and CI workflows ensure integration integrity.

## Diagram (Mermaid)

```mermaid
flowchart TD

    A["Ruby Application"]:::app

    subgraph "High-Level Ruby API"
        HTS_Bam["HTS::Bam API"]:::highAPI
        HTS_Bcf["HTS::Bcf API"]:::highAPI
        HTS_Faidx["HTS::Faidx API"]:::highAPI
        HTS_Tabix["HTS::Tabix API"]:::highAPI
    end

    subgraph "Low-Level FFI Bindings"
        LibHTS["LibHTS FFI Bindings"]:::lowFFI
        FFI_Helper["FFI Helper Modules"]:::lowFFI
    end

    subgraph "Native HTSlib C Library"
        HTSlib["HTSlib (C Library)"]:::native
    end

    subgraph "Supporting Tools"
        Support_Conversion["Conversion Tools"]:::support
        Support_Examples["Examples"]:::support
        Support_Tests["Tests"]:::support
        Support_CI["CI/CD & Build Tools"]:::support
    end

    %% Connections from Ruby Application to High-Level API
    A -->|"calls"| HTS_Bam
    A -->|"calls"| HTS_Bcf
    A -->|"calls"| HTS_Faidx
    A -->|"calls"| HTS_Tabix

    %% High-Level API to Low-Level FFI Bindings
    HTS_Bam -->|"API_call"| LibHTS
    HTS_Bcf -->|"API_call"| LibHTS
    HTS_Faidx -->|"API_call"| LibHTS
    HTS_Tabix -->|"API_call"| LibHTS

    %% Low-Level FFI Bindings to Native HTSlib
    LibHTS -->|"FFI_call"| HTSlib
    HTSlib -->|"returns"| LibHTS

    %% Internal FFI Binding usage
    LibHTS -->|"uses"| FFI_Helper

    %% Supporting Tools interactions (dashed connections)
    Support_Conversion -.->|"generates"| LibHTS
    Support_Examples -.->|"demonstrate"| HTS_Bam
    Support_Tests -.->|"validate"| HTS_Bam
    Support_CI -.->|"builds"| A

    %% Click Events
    click HTS_Bam "https://github.com/kojix2/ruby-htslib/blob/develop/lib/hts/bam.rb"
    click HTS_Bcf "https://github.com/kojix2/ruby-htslib/blob/develop/lib/hts/bcf.rb"
    click HTS_Faidx "https://github.com/kojix2/ruby-htslib/blob/develop/lib/hts/faidx.rb"
    click HTS_Tabix "https://github.com/kojix2/ruby-htslib/blob/develop/lib/hts/tabix.rb"
    click LibHTS "https://github.com/kojix2/ruby-htslib/blob/develop/lib/hts/libhts.rb"
    click FFI_Helper "https://github.com/kojix2/ruby-htslib/tree/develop/lib/hts/ffi_ext"
    click HTSlib "https://github.com/kojix2/ruby-htslib/tree/develop/htslib"
    click Support_Conversion "https://github.com/kojix2/ruby-htslib/tree/develop/scripts"
    click Support_Examples "https://github.com/kojix2/ruby-htslib/tree/develop/examples"
    click Support_Tests "https://github.com/kojix2/ruby-htslib/tree/develop/test"
    click Support_CI "https://github.com/kojix2/ruby-htslib/tree/develop/.github/workflows"

    %% Styles
    classDef app fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef highAPI fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef lowFFI fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef native fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef support fill:#fff3cd,stroke:#856404,stroke-width:2px;
```