# bojarlab/glycowork architecture

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

- Interactive diagram: https://gitdiagram.com/bojarlab/glycowork
- Repository: https://github.com/bojarlab/glycowork

## Overview

##### Main Components
a. **Package Modules (Code)**
- **core**: Fundamental utilities and shared functions
- **glycan_data**: Data loaders and helpers for CSV/JSON/Pickle datasets
- **ml**: Model training, inference, and helper pipelines
- **motif**: Motif detection, annotation, graph algorithms, drawing
- **network**: Biosynthetic/network analysis functions
b. **Static Resources**
- CSV/JSON/PKL files under `glycowork/glycan_data`, `glycowork/motif`, `glycowork/network`
- Pretrained deep‐learning models (downloaded via `prep_model`)
c. **User Interfaces**
- **Python API** (import `glycowork` in scripts or notebooks)
- **CLI/GUI**: `glycoworkGUI.py` executable
d. **Development & Deployment**
- **Notebooks** (`00_core.ipynb` … `05_examples.ipynb`)
- **Tests** (`tests/`)
- **CI/CD**: GitHub Actions, Docker (`docker-compose.yml`)

##### Relationships & Data Flows
- **User** → selects interface
- CLI/GUI → invokes core/modules
- Notebook/Python → `import glycowork` → calls modules
- **core** orchestrates calls into other modules.
- **glycan_data** loads static files → returns DataFrames/objects to
- **motif**, **ml**, **network**
- **motif** and **network** transform sequences into graphs or features.
- **ml** consumes features (from `motif` or direct from `glycan_data`) → trains/models → optionally writes outputs or returns predictions.
- **prep_model** (in **ml**) retrieves pretrained models from remote storage.
- **Tests** validate each module independently.

##### Architectural Patterns & Principles
- **Modular Separation of Concerns**: each subpackage focuses on one domain
- **Resource Abstraction**: data files treated as internal “database”
- **Extensibility Points**:
- Optional extras (`glycowork[ml]`, `[chem]`)
- Clear module APIs for adding new motif/dataset types
- **Plugin-style CLI/GUI**: wraps core APIs

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    User["User"]:::external

    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        CLI["CLI/GUI"]:::ui
        Notebook["Notebooks / Scripts"]:::ui
    end

    %% Core
    Core["core"]:::code

    %% Modules
    subgraph "Code Modules"
        direction TB
        GD["glycan_data"]:::code
        Motif["motif"]:::code
        ML["ml"]:::code
        Net["network"]:::code
        Prep["prep_model"]:::code
    end

    %% Static Resources
    subgraph "Static Resources"
        direction TB
        GDData["Datasets (CSV/JSON/PKL)"]:::static
        NetData["Network Data (PKL/CSV)"]:::static
        MLData["Background Correction CSV"]:::static
    end

    %% External
    ExtRepo["External Model Repo"]:::external

    %% Tests & CI/CD
    Tests["tests/"]:::infra
    CICD["CI/CD & Docker"]:::infra

    %% Connections
    User --> CLI
    User --> Notebook
    CLI --> Core
    Notebook --> Core
    Core --> GD
    Core --> Motif
    Core --> ML
    Core --> Net
    Core --> Prep
    GD --> GDData
    Motif --> GDData
    ML --> Motif
    ML --> GDData
    ML --> MLData
    Net --> GDData
    Net --> NetData
    Prep --> ExtRepo
    Tests --> Core
    Tests --> GD
    Tests --> Motif
    Tests --> ML
    Tests --> Net
    CICD --> Core
    CICD --> Tests

    %% Click Events
    click Core "https://github.com/bojarlab/glycowork/blob/master/glycowork/core.py"
    click GD "https://github.com/bojarlab/glycowork/blob/master/glycowork/glycan_data.py"
    click GD "https://github.com/bojarlab/glycowork/tree/master/glycowork/glycan_data/"
    click GDData "https://github.com/bojarlab/glycowork/tree/master/glycowork/glycan_data/"
    click GDData "https://github.com/bojarlab/glycowork/blob/master/glycowork/glycan_data/loader.py"
    click GDData "https://github.com/bojarlab/glycowork/blob/master/glycowork/glycan_data/stats.py"
    click GDData "https://github.com/bojarlab/glycowork/blob/master/glycowork/glycan_data/data_entry.py"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml.py"
    click ML "https://github.com/bojarlab/glycowork/tree/master/glycowork/ml/"
    click MLData "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/glycowork_lectinoracle_background_correction.csv"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/inference.py"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/model_training.py"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/models.py"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/processing.py"
    click ML "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/train_test_split.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif.py"
    click Motif "https://github.com/bojarlab/glycowork/tree/master/glycowork/motif/"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/analysis.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/annotate.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/graph.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/tokenization.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/draw.py"
    click Motif "https://github.com/bojarlab/glycowork/blob/master/glycowork/motif/processing.py"
    click Net "https://github.com/bojarlab/glycowork/blob/master/glycowork/network.py"
    click Net "https://github.com/bojarlab/glycowork/tree/master/glycowork/network/"
    click Net "https://github.com/bojarlab/glycowork/blob/master/glycowork/network/biosynthesis.py"
    click Net "https://github.com/bojarlab/glycowork/blob/master/glycowork/network/evolution.py"
    click NetData "https://github.com/bojarlab/glycowork/blob/master/glycowork/network/milk_networks_exhaustive.pkl"
    click NetData "https://github.com/bojarlab/glycowork/blob/master/glycowork/network/monolink_to_enzyme.csv"
    click Prep "https://github.com/bojarlab/glycowork/blob/master/glycowork/ml/inference.py"
    click CLI "https://github.com/bojarlab/glycowork/blob/master/bin/glycoworkGUI.py"
    click User "https://github.com/bojarlab/glycowork/blob/master/glycowork/__init__.py"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/00_core.ipynb"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/01_glycan_data.ipynb"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/02_ml.ipynb"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/03_motif.ipynb"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/04_network.ipynb"
    click Notebook "https://github.com/bojarlab/glycowork/blob/master/05_examples.ipynb"
    click Tests "https://github.com/bojarlab/glycowork/tree/master/tests/"
    click Tests "https://github.com/bojarlab/glycowork/blob/master/tests/test_core_functions.py"
    click CICD "https://github.com/bojarlab/glycowork/tree/master/.github/workflows/"
    click CICD "https://github.com/bojarlab/glycowork/blob/master/docker-compose.yml"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef static fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ui fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef infra fill:#DCDCDC,stroke:#000,stroke-width:1px
```
