# sivasubramanics/kcftools architecture

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

- Interactive diagram: https://gitdiagram.com/sivasubramanics/kcftools
- Repository: https://github.com/sivasubramanics/kcftools

## Overview

##### Project Type & Purpose
- Type: Command‐line bioinformatics tool (no GUI/web frontend).
- Purpose: Identify genomic variations by comparing reference *k*-mers against query k-mer databases (KMC), produce `.kcf`, TSV, JSON, cohort files, etc.

##### Top‐Level Components
a. CLI Parser & Dispatcher
– Class: `KCFTOOLS.java` (main method, argument parsing).
– Uses a “Plugin Manager” (loads/dispatches commands).
b. Plugin Layer (Command Pattern)
– Each plugin implements `execute(args)` and orchestrates processing steps.

##### Core Processing Layer
For each plugin, illustrate its internal flow:
– **Input Readers**
- FASTA reader: `Data/Fasta` + `FastaIndex`
- KMC DB reader: `Data/KMC`
- GTF reader: `Data/GTF`
- KCF reader: `Data/KCFReader` (for commands that ingest `.kcf`)
– **Variation Engine** (for getVariations & related)
- Windowing logic: `Data/Window`
- K-mer operations: `Data/Kmer`, `Data/Signature`
- Distance & scoring calculations: encapsulated in plugin + helper functions
– **Output Writers**
- KCF writer: `Data/KCFWriter`
- TSV/JSON: (Plugins or generic code serializing to TSV/JSON)
– **Data Structures**
- `Data` package classes (e.g., `Data.java`, `Signature.java`, `Window.java`) represent in‐memory models.

##### Utility Services
– `Utils/Configs.java` (configuration loading)
– `Utils/Logger.java` (logging)
– `Utils/HelperFunctions.java` (common routines)
These are injected or called by both the CLI dispatcher and all plugins.

##### External Dependencies & Resources
– **File System**
- Reference FASTA files
- GTF annotation files
- Input `.kcf` files (for some commands)
– **KMC Database**
- KMC3 on‐disk DB files (`<prefix>.kmc_pre`, etc.)
– **Third‐party Tools/Frameworks**
- Java 17+ runtime
- Maven build system
- Logging framework (if external)
– **Script Utilities** (in `utils/` folder)
- Shell wrapper: `run_kcftools.sh`
- Plot scripts: `plotIBS.R`, `plotVariationHistogram.py`, etc.
These are “outside” your core application but important for workflows.

##### Relationships & Data Flow
- Sequence:
1. User runs `kcftools getVariations …`
2. CLI Parser instantiates `GetVariations` plugin
3. Plugin reads FASTA & KMC DB
4. Plugin loops windows, queries k-mers, computes scores
5. Plugin streams results to `KCFWriter`
6. Resulting `.kcf` file on disk

##### Architectural Patterns & Design Principles
- **Command Pattern**: each subcommand is its own plugin class.
- **Layered Architecture**:
– CLI Layer
– Orchestration/Plugin Layer
– Core Logic Layer (Data models + algorithms)
– I/O Layer (file readers/writers)
– Utility Layer (common services)
- **Separation of Concerns**: I/O separated from computation, configuration separate from code, logging centralized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph " "
        direction TB
        CLI["KCFTOOLS CLI"]:::cli
    end
    click CLI "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/KCFTOOLS.java"

    %% Plugin Layer
    subgraph "Plugin Layer" 
        direction TB
        GV["Get Variations"]:::plugin
        CO["Cohort"]:::plugin
        FI["Find IBS"]:::plugin
        CI["Compare IBS"]:::plugin
        GA["Get Attributes"]:::plugin
        SK["Split KCF"]:::plugin
        KT["KCF to TSV"]:::plugin
        KM["KCF to Matrix"]:::plugin
        KP["KCF to PED"]:::plugin
        IW["Increase Windows"]:::plugin
    end
    click GV "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/GetVariants.java"
    click CO "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/Cohort.java"
    click FI "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/FindIBS.java"
    click CI "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/CompareIBS.java"
    click GA "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/GetAttributes.java"
    click SK "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/SplitKCF.java"
    click KT "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/KCFToTSV.java"
    click KM "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/KCFToMatrix.java"
    click KP "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/KCFToPed.java"
    click IW "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Plugins/IncreaseWindows.java"

    %% Core Processing / Data I/O Layer
    subgraph "Core Data / I/O Layer"
        direction TB
        subgraph "Data Models" 
            direction TB
            DM["Data.java"]:::core
            KH["KCFHeader.java"]:::core
            SG["Signature.java"]:::core
            KR["Kmer.java"]:::core
            WD["Window.java"]:::core
        end
        subgraph "Input Readers"
            direction TB
            FA["Fasta.java"]:::core
            FI2["FastaIndex*.java"]:::core
            GT["GTF.java"]:::core
            KMCR["KMC.java"]:::core
            KCR["KCFReader.java"]:::core
        end
        subgraph "Output Writers"
            direction TB
            KW["KCFWriter.java"]:::core
            TW["TSV/JSON Writers"]:::core
        end
    end
    click DM "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/Data.java"
    click KH "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/KCFHeader.java"
    click SG "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/Signature.java"
    click KR "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/Kmer.java"
    click WD "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/Window.java"
    click FA "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/Fasta.java"
    click FI2 "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/FastaIndex.java"
    click GT "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/GTF.java"
    click KMCR "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/KMC.java"
    click KCR "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/KCFReader.java"
    click KW "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Data/KCFWriter.java"

    %% Utility Services
    subgraph "Utils" 
        direction TB
        UC["Configs.java"]:::utils
        UL["Logger.java"]:::utils
        UH["HelperFunctions.java"]:::utils
    end
    click UC "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Utils/Configs.java"
    click UL "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Utils/Logger.java"
    click UH "https://github.com/sivasubramanics/kcftools/blob/main/src/main/java/nl/wur/bis/kcftools/Utils/HelperFunctions.java"

    %% External Resources
    subgraph "External Resources"
        direction TB
        FS[(FASTA Files)]:::external
        GTFR[(GTF Files)]:::external
        KMCDB[(KMC DB)]:::external
        INKCF[(Input .kcf)]:::external
        SCRIPTS[(Workflow Scripts)]:::external
    end

    %% Workflow Scripts
    subgraph "Scripts"
        direction TB
        SH["run_kcftools.sh"]:::external
        R1["plotIBS.R"]:::external
        PY["plotVariationHistogram.py"]:::external
        R2["plot_introgressions.R"]:::external
    end
    click SH "https://github.com/sivasubramanics/kcftools/blob/main/utils/run_kcftools.sh"
    click R1 "https://github.com/sivasubramanics/kcftools/blob/main/utils/plotIBS.R"
    click PY "https://github.com/sivasubramanics/kcftools/blob/main/utils/plotVariationHistogram.py"
    click R2 "https://github.com/sivasubramanics/kcftools/blob/main/utils/plot_introgressions.R"

    %% Connections
    CLI -->|"dispatches"| GV
    CLI -->|"dispatches"| CO
    CLI -->|"dispatches"| FI
    CLI -->|"dispatches"| CI
    CLI -->|"dispatches"| GA
    CLI -->|"dispatches"| SK
    CLI -->|"dispatches"| KT
    CLI -->|"dispatches"| KM
    CLI -->|"dispatches"| KP
    CLI -->|"dispatches"| IW

    subgraph PluginFlows
        direction TB
        GV -->|"reads FASTA"| FA
        GV -->|"reads KMC"| KMCR
        GV -->|"reads GTF"| GT
        GV -->|"reads KCF"| KCR
        GV -->|"uses Window/Kmer/Signature"| WD
        GV -->|"writes .kcf"| KW
        GV -->|"writes TSV/JSON"| TW
    end

    %% Shared Utilities
    CLI -.-> UC
    CLI -.-> UL
    CLI -.-> UH
    GV -.-> UC
    CO -.-> UH
    FI -.-> UL
    CI -.-> UC
    GA -.-> UH
    SK -.-> UL
    KT -.-> UC
    KM -.-> UH
    KP -.-> UL
    IW -.-> UC

    %% Data readers to external
    FA -->|"FASTA on disk"| FS
    KMCR -->|"KMC DB files"| KMCDB
    GT -->|"GTF on disk"| GTFR
    KCR -->|"input .kcf"| INKCF
    KW -->|"KCF output"| INKCF

    %% Scripts
    SCRIPTS --> SH
    SCRIPTS --> R1
    SCRIPTS --> PY
    SCRIPTS --> R2

    %% Styles
    classDef cli fill:#9f6,stroke:#363,stroke-width:2px
    classDef plugin fill:#afa,stroke:#070,stroke-width:1px
    classDef core fill:#6cf,stroke:#039,stroke-width:1px
    classDef utils fill:#fb3,stroke:#ca0,stroke-width:1px
    classDef external fill:#ccc,stroke:#888,stroke-width:1px,stroke-dasharray: 2 2
```
