# samtools/htslib architecture

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

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

## Overview

##### Main Components

a. Core Library Components:
- File Format Handlers
- SAM/BAM Handler
- CRAM Handler
- VCF/BCF Handler
- Tabix Indexer
- Compression Layer (BGZip)
- Index Management (CSI/BAI/TBI)
- Threading System
- I/O Abstraction Layer

b. External Dependencies:
- zlib (compression library)
- Operating System I/O
- Optional cloud storage interfaces (S3, GCS)

##### Component Relationships

**┌─────────────────────── Client Applications ───────────────────────┐**
- (samtools, bcftools, other bioinformatics tools)                 │
- Public API Layer ──────────────────────────┤
- ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
- SAM/BAM │ │  CRAM   │ │ VCF/BCF │ │ FAIDX   │ │ Thread Pool │ │
- ┘ └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │
- Internal Implementation ─────────────────────┤
- ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────┐           │
- BGZF   │ │  Index  │ │ HTScodec │ │ Text Utils │           │
- ┘ └─────────┘ └──────────┘ └────────────┘           │
- I/O Layer ───────────────────────────────┤
- ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────┐          │
- Local   │ │   S3    │ │   GCS    │ │ HTTP/HTTPS │          │
- ┘ └─────────┘ └──────────┘ └────────────┘          │
- ┘

##### Important Details

a. File Format Support:
- Supported formats (SAM, BAM, CRAM, VCF, BCF)
- Index format support (CSI, BAI, TBI)

b. Threading Model:
- Thread pool implementation
- Parallel processing capabilities

c. I/O Abstractions:
- Local file system
- Remote storage (S3, GCS)
- HTTP/HTTPS access

##### Key Architectural Patterns

- Plugin Architecture: Show how the storage backends are pluggable
- Threading Model: Illustrate the thread pool design
- Buffering System: Show BGZF compression integration
- Index Management: Show relationship between formats and indices

##### Implementation Notes

- Version information
- Notes about performance characteristics
- Format conversion paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style definitions
    classDef client fill:#a8d1ff,stroke:#333,stroke-width:2px
    classDef api fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef io fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:2px

    %% Client Applications Layer
    subgraph ClientApps
        CA["Client Applications<br>(samtools, bcftools, etc)"]
    end
    class CA client

    %% Public API Layer
    subgraph PublicAPI
        CoreInterface["Core Library Interface"]
        SAM["SAM/BAM Handler"]
        CRAM["CRAM Handler"]
        VCF["VCF/BCF Handler"]
        FAIDX["FAIDX"]
        ThreadPool["Thread Pool"]
    end

    %% Internal Implementation Layer
    subgraph Internal
        BGZF["BGZF Compression"]
        Index["Index Management"]
        HTSCodec["HTScodec"]
        TextUtils["Text Utils"]
    end

    %% I/O Layer
    subgraph IOLayer
        Local["Local Storage"]
        S3["S3 Storage"]
        GCS["GCS Storage"]
        HTTP["HTTP/HTTPS"]
    end

    %% External Dependencies
    subgraph External
        Zlib["zlib"]
        OS["Operating System I/O"]
    end

    %% Relationships
    CA --> CoreInterface
    CA --> SAM
    CA --> CRAM
    CA --> VCF
    
    CoreInterface --> SAM
    CoreInterface --> CRAM
    CoreInterface --> VCF
    CoreInterface --> FAIDX
    CoreInterface --> ThreadPool
    
    SAM --> BGZF
    CRAM --> BGZF
    VCF --> BGZF
    
    SAM --> Index
    CRAM --> Index
    VCF --> Index
    
    BGZF --> Zlib
    
    BGZF --> Local
    BGZF --> S3
    BGZF --> GCS
    BGZF --> HTTP
    
    Local --> OS
    S3 --> OS
    GCS --> OS
    HTTP --> OS

    %% Click events for component mapping
    click SAM "https://github.com/samtools/htslib/blob/develop/sam.c"
    click CRAM "https://github.com/samtools/htslib/blob/develop/cram/cram.h"
    click VCF "https://github.com/samtools/htslib/blob/develop/vcf.c"
    click FAIDX "https://github.com/samtools/htslib/blob/develop/faidx.c"
    click BGZF "https://github.com/samtools/htslib/blob/develop/bgzf.c"
    click ThreadPool "https://github.com/samtools/htslib/blob/develop/thread_pool.c"
    click Local "https://github.com/samtools/htslib/blob/develop/hfile.c"
    click S3 "https://github.com/samtools/htslib/blob/develop/hfile_s3.c"
    click GCS "https://github.com/samtools/htslib/blob/develop/hfile_gcs.c"
    click HTTP "https://github.com/samtools/htslib/blob/develop/hfile_libcurl.c"
    click Index "https://github.com/samtools/htslib/blob/develop/cram/cram_index.c"
    click CoreInterface "https://github.com/samtools/htslib/blob/develop/hts.c"

    %% Legend
    subgraph Legend
        L1["Client Applications"]:::client
        L2["Public API"]:::api
        L3["Core Components"]:::core
        L4["I/O Layer"]:::io
        L5["External Dependencies"]:::ext
    end

    %% Class assignments
    class SAM,CRAM,VCF,FAIDX,ThreadPool,CoreInterface api
    class BGZF,Index,HTSCodec,TextUtils core
    class Local,S3,GCS,HTTP io
    class Zlib,OS ext
```
