# fnadalin/gapfiller architecture

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

- Interactive diagram: https://gitdiagram.com/fnadalin/gapfiller
- Repository: https://github.com/fnadalin/gapfiller

## Overview

##### Project Type and Purpose
- This is a single‐binary, command-line C++ application (“GapFiller”) for de-novo local assembly to fill sequence gaps between paired reads.
- It is not a multi-tier web app or microservices system. Rather, it is a modular, self-contained bioinformatics tool that reads input files, processes them in memory, and writes output files.

##### High-Level Components
A. CLI & Options Manager
B. I/O Layer
C. Data Structures & Storage
D. Assembly Engine (Core Algorithm)
E. Error Handling
F. Output Generation
G. Third-Party Libraries (Boost, zlib, samtools code)

##### Relationships and Data Flow
1. CLI & Options Manager
- Parses command-line args (seed files, query files, parameters).
- Populates an Options singleton (src/options/*).
2. I/O Layer
- Auto-detects file types (fasta/fastq/SAM/BAM, gz/bz2) via Auto_Unzip/Auto_Zip modules (src/io).
- Streams raw reads into memory structures.
- Feeds seeds into the Assembly Engine and optional query reads.
3. Data Structures & Storage
- In-memory representations: Reads, Contig, Layout_list/vector, Hash tables (src/data_structures/*).
- Builds fingerprint hash index (k-mers) for fast overlap lookups.
4. Assembly Engine
- Uses modules/Assembly*.cpp classes: seed-and-extend algorithm.
- Performs overlap detection via hash index, consensus extension, stop-criteria checks (insert size exceeded, repeats, no more reads, etc.).
- Optionally records layout (src/modules/Assembly_store_layout).
5. Error Handling
- Centralized exception classes (src/errors/*) catch I/O, format, data errors, and propagate to CLI for reporting or abort.
6. Output Generation
- Writes contigs.fasta, contigs_trash.fasta, contigs.stats, and optional .layout files.
- Uses Binary/Fastq/Sam writers in the I/O layer, plus compression modules.
7. Third-Party Libraries
- Boost: for configurations, possibly threading or data structures.
- zlib: gzip compression support.
- Samtools code (src/samtools/*): in-process C library for BAM/SAM parsing and indexing.

- From CLI → Options Manager → Assembly Engine and I/O Layer
- From I/O Layer → Data Structures → Assembly Engine
- From Assembly Engine ↔ Data Structures (read/write)
- Assembly Engine → Output Generation → Files on disk
- Errors at any stage → Error Handling → CLI (exit/report)

##### Architectural Patterns and Design Principles
- Modular layering: clear separation between CLI parsing, I/O, core algorithm, data structures, and error handling.
- Singleton pattern for options.
- Strategy pattern for different input/output formats (via polymorphic Auto_Unzip/Auto_Zip, Binary, Fastq, Sam classes).
- In-memory hash indexing for fast lookup (parameterized by k and block length).

##### Detailed Elements
- Component labels: “Options::Singleton”, “Auto_Unzip”, “Hash”, “Assembly::extend()”, etc.
- “Read seeds & queries” → Hash build → “Find overlaps” → “Extend contig” → “Write contig”
- Modules for both FASTA/FASTQ and SAM/BAM reading.
- Compression subprocess (Auto_Zip) before writing .gz outputs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "CLI & Options Manager"
        direction TB
        GF["GapFiller.cpp"]:::cli
        Opt["Options::Singleton"]:::cli
        Menu["Menu.cpp/h"]:::cli
    end

    subgraph "I/O Layer"
        direction TB
        AU["Auto_Unzip"]:::io
        AZ["Auto_Zip"]:::io
        Bin["Binary"]:::io
        FQ["Fastq"]:::io
        SamIO["Sam"]:::io
    end

    subgraph "Data Structures & Storage"
        direction TB
        Reads["Reads"]:::data
        Contig["Contig"]:::data
        LayoutList["Layout_list/Vector"]:::data
        HashIdx["Hash"]:::data
    end

    subgraph "Assembly Engine (Core Algorithm)"
        direction TB
        AssmCore["Assembly::extend()"]:::core
        AssmStore["Assembly_store_layout"]:::core
    end

    subgraph "Output Generation"
        direction TB
        OutIO["I/O Writers + Auto_Zip"]:::io
        Files["Files on Disk"]:::disk
    end

    subgraph "Error Handling"
        direction TB
        Err["Exception Classes"]:::error
    end

    subgraph "Third-Party Libraries"
        direction TB
        Boost["Boost"]:::third
        Zlib["zlib (bgzf)"]:::third
        Samtools["samtools code"]:::third
    end

    %% Data flow arrows
    GF -->|parses args| Opt
    Opt -->|"config"| AssmCore
    Opt -->|"config"| AU
    AU -->|"ReadRecords"| Reads
    AZ -->|"Compress outputs"| OutIO
    Bin -->|"ReadRecords"| Reads
    FQ -->|"ReadRecords"| Reads
    SamIO -->|"ReadRecords"| Reads

    Reads -->|"build HashIndex"| HashIdx
    HashIdx -->|"lookup overlaps"| AssmCore
    AssmCore -->|"read/write"| Reads
    AssmCore -->|"extend contig"| Contig
    AssmCore -->|"store layout (opt)"| AssmStore
    Contig -->|"contig records"| OutIO
    AssmCore -->|"stats"| OutIO
    OutIO -->|"write files"| Files

    %% Error flow
    GF -.->|errors| Err
    AU -.->|errors| Err
    Bin -.->|errors| Err
    FQ -.->|errors| Err
    SamIO -.->|errors| Err
    AssmCore -.->|errors| Err
    Err -->|report/exit| GF

    %% Third-party deps
    AU -->|uses| Zlib
    SamIO -->|uses| Samtools
    GF -->|uses| Boost

    %% Click events
    click GF "https://github.com/fnadalin/gapfiller/blob/master/src/GapFiller.cpp"
    click Opt "https://github.com/fnadalin/gapfiller/blob/master/src/options/Options.cpp"
    click Opt "https://github.com/fnadalin/gapfiller/blob/master/src/options/Options.h"
    click Opt "https://github.com/fnadalin/gapfiller/blob/master/src/options/Singleton.cpp"
    click Opt "https://github.com/fnadalin/gapfiller/blob/master/src/options/Singleton.h"
    click Menu "https://github.com/fnadalin/gapfiller/blob/master/src/options/Menu.cpp"
    click Menu "https://github.com/fnadalin/gapfiller/blob/master/src/options/Menu.h"

    click AU "https://github.com/fnadalin/gapfiller/blob/master/src/io/Auto_Unzip.cpp"
    click AU "https://github.com/fnadalin/gapfiller/blob/master/src/io/Auto_Unzip.h"
    click AZ "https://github.com/fnadalin/gapfiller/blob/master/src/io/Auto_Zip.cpp"
    click AZ "https://github.com/fnadalin/gapfiller/blob/master/src/io/Auto_Zip.h"
    click Bin "https://github.com/fnadalin/gapfiller/blob/master/src/io/Binary.cpp"
    click Bin "https://github.com/fnadalin/gapfiller/blob/master/src/io/Binary.h"
    click FQ "https://github.com/fnadalin/gapfiller/blob/master/src/io/Fastq.cpp"
    click FQ "https://github.com/fnadalin/gapfiller/blob/master/src/io/Fastq.h"
    click SamIO "https://github.com/fnadalin/gapfiller/blob/master/src/io/Sam.cpp"
    click SamIO "https://github.com/fnadalin/gapfiller/blob/master/src/io/Sam.h"

    click Reads "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Reads.cpp"
    click Reads "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Reads.h"
    click Contig "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Contig.cpp"
    click Contig "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Contig.h"
    click LayoutList "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Layout_list.cpp"
    click LayoutList "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Layout_list.h"
    click LayoutList "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Layout_vector.cpp"
    click LayoutList "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Layout_vector.h"
    click HashIdx "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Hash.cpp"
    click HashIdx "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/Hash.h"
    click Reads "https://github.com/fnadalin/gapfiller/blob/master/src/data_structures/include.h"

    click AssmCore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly.cpp"
    click AssmCore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly.h"
    click AssmCore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly_only_sequence.cpp"
    click AssmCore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly_only_sequence.h"
    click AssmStore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly_store_layout.cpp"
    click AssmStore "https://github.com/fnadalin/gapfiller/blob/master/src/modules/Assembly_store_layout.h"

    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Data_Exception.cpp"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Data_Exception.h"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Data_Not_Found.cpp"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Data_Not_Found.h"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/File_Not_Found.cpp"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/File_Not_Found.h"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Generic_Exception.cpp"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Generic_Exception.h"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Incorrect_Format.cpp"
    click Err "https://github.com/fnadalin/gapfiller/blob/master/src/errors/Incorrect_Format.h"

    click Samtools "https://github.com/fnadalin/gapfiller/tree/master/src/samtools/"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,stroke-width:1px
    classDef io fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#32CD32,stroke:#333,stroke-width:1px
    classDef error fill:#FF6347,stroke:#333,stroke-width:1px
    classDef third fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef disk fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
