# helicalai/helical architecture

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

- Interactive diagram: https://gitdiagram.com/helicalai/helical
- Repository: https://github.com/helicalai/helical

## Overview

##### Overall Project Scope & Main Components
- Core Package (helical module): This is the heart of the project. It contains the main API, utility functions, and the abstraction layers for different models.
- Models Subsystem (helical/models): Under this directory you have separate subdirectories for each model (caduceus, evo_2, geneformer, helix_mrna, hyena_dna, mamba2_mrna, scgpt, uce). Each model folder typically contains configuration files, tokenizers, fine-tuning implementations, and model definitions. This clearly represents a plug‐in architecture where different bio foundation models can be selected.
- Auxiliary Utilities (helical/utils): This contains helper modules for logging, data conversion, downloading, and mapping which are used across the entire codebase.
- CI/CD and Testing (ci, .github/workflows): These directories indicate continuous integration pipelines for testing the package (unit tests in ci/tests across various models and utility modules) and automating releases.
- Documentation & External Assets: The docs, examples, and configuration files (e.g., Dockerfile, singularity.def) support deployment, usage, and developer onboarding. The examples directory shows notebooks and scripts that demonstrate using the API, and the documentation is built to guide users.
- Configuration & Build Scripts: Files like Dockerfile, entrypoint.sh, and config files (such as _config.yml, mkdocs.yml) manage deployment, documentation building, and containerization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        UI["User/CLI"]:::user
    end

    subgraph "Documentation & Examples"
        DOC["Documentation"]:::docs
        EX["Examples"]:::docs
    end

    subgraph "Core Helical Framework"
        CORE["Core API Module"]:::core
    end

    subgraph "Models Subsystem"
        m1["Caduceus"]:::model
        m2["Evo_2"]:::model
        m3["Geneformer"]:::model
        m4["Helix_mRNA"]:::model
        m5["Hyena_DNA"]:::model
        m6["Mamba2_mRNA"]:::model
        m7["SCGPT"]:::model
        m8["UCE"]:::model
    end

    subgraph "Auxiliary Utilities"
        UTILS["Utilities"]:::utils
    end

    subgraph "CI/CD & Testing"
        CI["CI Workflows"]:::ci
        TEST["Testing Pipeline"]:::ci
    end

    subgraph "Deployment/Build Scripts"
        DF["Dockerfile"]:::build
        SING["Singularity.def"]:::build
        ENTRY["Entrypoint.sh"]:::build
        CONFIG["Config Files"]:::build
    end

    %% Connections between components
    UI -->|"calls"| EX
    UI -->|"calls"| DOC
    EX -->|"calls"| CORE
    DOC -->|"docs"| CORE
    CORE -->|"loads"| m1
    CORE -->|"loads"| m2
    CORE -->|"loads"| m3
    CORE -->|"loads"| m4
    CORE -->|"loads"| m5
    CORE -->|"loads"| m6
    CORE -->|"loads"| m7
    CORE -->|"loads"| m8
    CORE -->|"uses"| UTILS
    CI -->|"tests"| CORE
    CI -->|"tests"| UTILS
    TEST -->|"triggers"| CI
    ENTRY -->|"bootstraps"| CORE
    DF -->|"deploys"| CORE
    SING -->|"deploys"| CORE
    CONFIG -->|"builds"| DOC

    %% Click Events
    click CORE "https://github.com/helicalai/helical/tree/release/helical/"
    click m1 "https://github.com/helicalai/helical/tree/release/helical/models/caduceus"
    click m2 "https://github.com/helicalai/helical/tree/release/helical/models/evo_2"
    click m3 "https://github.com/helicalai/helical/tree/release/helical/models/geneformer"
    click m4 "https://github.com/helicalai/helical/tree/release/helical/models/helix_mrna"
    click m5 "https://github.com/helicalai/helical/tree/release/helical/models/hyena_dna"
    click m6 "https://github.com/helicalai/helical/tree/release/helical/models/mamba2_mrna"
    click m7 "https://github.com/helicalai/helical/tree/release/helical/models/scgpt"
    click m8 "https://github.com/helicalai/helical/tree/release/helical/models/uce"
    click UTILS "https://github.com/helicalai/helical/tree/release/helical/utils/"
    click CI "https://github.com/helicalai/helical/tree/release/.github/workflows/"
    click TEST "https://github.com/helicalai/helical/tree/release/ci/tests/"
    click DOC "https://github.com/helicalai/helical/tree/release/docs/"
    click EX "https://github.com/helicalai/helical/tree/release/examples/"
    click DF "https://github.com/helicalai/helical/tree/release/Dockerfile"
    click SING "https://github.com/helicalai/helical/blob/release/singularity.def"
    click ENTRY "https://github.com/helicalai/helical/blob/release/entrypoint.sh"
    click CONFIG "https://github.com/helicalai/helical/blob/release/_config.yml"

    %% Class Definitions for colors
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef model fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef utils fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef ci fill:#F08080,stroke:#000,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef build fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef user fill:#E0FFFF,stroke:#000,stroke-width:1px;
```
