# bioinfomachinelearning/flowdock architecture

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

- Interactive diagram: https://gitdiagram.com/bioinfomachinelearning/flowdock
- Repository: https://github.com/bioinfomachinelearning/flowdock

## Overview

##### Project type and purpose
- FlowDock is a full-stack research codebase for generative protein–ligand docking and affinity prediction.
- Core technologies: PyTorch + PyTorch Lightning for model training, Hydra for configuration management, assorted bioinformatics tools (ESM2, ESMFold, US-align), and experiment tracking/logging frameworks (WandB, MLflow, Comet, TensorBoard, etc.).

##### Top-level structure (from the file tree)
- CLI entry points:
- flowdock/train.py (training)
- flowdock/eval.py (evaluation)
- flowdock/sample.py (inference/sampling)
- Configuration: configs/ (Hydra config groups: data, model, trainer, strategy, callbacks, logger, etc.)
- Core package: flowdock/
- flowdock/data (data modules & preprocessing scripts)
- flowdock/models (model definitions, loss, flow-matching modules)
- flowdock/utils (helper functions, logging utils, metric utils)
- Data storage: data/ (raw & preprocessed datasets), checkpoints/ (model weights)
- Supporting scripts, notebooks, Dockerfile, CI, Makefile, tests

##### Main components
a. Configuration Manager (Hydra)
- Loads YAML configs from configs/
- Injects settings into CLI scripts and instantiation of components
b. CLI Layer
- Entry points: train.py, eval.py, sample.py
- Parse CLI args → initialize Hydra → instantiate components
c. Data Pipeline
- Raw data (PDBBind, MOAD, DockGen, PLINDER…) in data/
- flowdock/data/components:
- sequence preparation → FASTA
- ESM2 embedding extraction
- ESMFold structure prediction
- apo-to-holo alignment (US-align)
- Datamodules (PyTorch Lightning DataModule) for batching and loading
d. Model + Training Engine
- flowdock/models/components: flow-matching modules, encoder, loss functions
- flowdock/models/flowdock_fm_module.py: LightningModule wrapping model forward, loss, optimizer, schedulers
- PyTorch Lightning Trainer: orchestrates training loop, validation, checkpointing
e. Callbacks & Loggers
- Hydra-configured callbacks: EarlyStopping, ModelCheckpoint, EMA, LR monitor, RichProgressBar, custom summaries
- Loggers: WandB, Comet, MLflow, TensorBoard, Neptune, CSV, etc.
f. Evaluation & Sampling
- eval.py: loads checkpoint + test DataModule → runs inference → collects metrics
- sample.py: loads checkpoint + prepares receptor/ligand inputs (single vs. batched) → runs generative sampler (VDODE, etc.) → outputs PDB trajectories + affinity estimates
g. Storage & Outputs
- Checkpoints (checkpoints/)
- Sampled structures (PDB files)
- Prediction metrics & plots (notebooks/)

##### Relationships & data flow
- CLI script → Hydra config → instantiate (DataModule, LightningModule, Trainer, Callbacks, Logger).
- DataModule reads raw data → applies preprocessing steps (ESM embeddings, ESMFold, alignment) → yields PyTorch batches.
- Trainer orchestrates forward/backward passes on model → uses callbacks to store checkpoints & track metrics via loggers.
- Eval pipeline mirrors train but with trainer.test(); metrics saved to disk / logger.
- Sample pipeline takes sequence + SMILES + optional template → model generates docking poses → writes output PDB files; logger optional.

##### Architectural patterns & design principles
- Modular separation: data, model, utils, configs, scripts
- Inversion of control via Hydra config
- Dependency injection: all components are hydra-instantiated
- PyTorch Lightning pattern: clear separation of data (DataModule), model logic (LightningModule), training loop (Trainer)
- Extensible logging & callback system (Hydra plugin pattern)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Legend
    subgraph "Legend"
        direction LR
        Cfg["Configuration Manager (Hydra)"]:::config
        DP["Data Pipeline"]:::data
        MT["Model & Training Engine"]:::model
        CL["Callbacks & Loggers"]:::callback
        EX["External Tools"]:::external
    end

    %% Configuration
    Cfg["Configuration Manager (Hydra)"]:::config
    click Cfg "https://github.com/bioinfomachinelearning/flowdock/tree/main/configs/"

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Train["Training CLI: train.py"]:::cli
        Eval["Evaluation CLI: eval.py"]:::cli
        Sample["Sampling CLI: sample.py"]:::cli
    end
    click Train "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/train.py"
    click Eval "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/eval.py"
    click Sample "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/sample.py"

    Cfg -->|loads configs| Train
    Cfg -->|loads configs| Eval
    Cfg -->|loads configs| Sample

    %% Data Pipeline
    subgraph "Data Pipeline" 
        direction TB
        Raw["Raw Data (PDBBind, MOAD, etc.)"]:::data
        Components["Preprocessing Components"]:::data
        CombinedDM["Combined DataModule"]:::data
        PlinderDM["PLINDER DataModule"]:::data
    end
    click Components "https://github.com/bioinfomachinelearning/flowdock/tree/main/flowdock/data/components/"
    click CombinedDM "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/data/combined_datamodule.py"
    click PlinderDM "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/data/plinder_datamodule.py"

    Train --> CombinedDM
    Train --> PlinderDM
    Eval --> CombinedDM
    Sample --> CombinedDM

    Raw --> Components
    Components --> CombinedDM
    Components --> PlinderDM

    %% External Tools
    subgraph "External Tools & Bioinformatics" 
        direction TB
        ESM2["ESM2 Embedding"]:::external
        ESMFold["ESMFold Structure Prediction"]:::external
        USAlign["US-align Alignment"]:::external
    end
    click ESM2 "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/data/components/esm_embedding_extraction.py"
    click ESMFold "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/data/components/esmfold_apo_to_holo_alignment.py"
    click USAlign "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/data/components/esmfold_apo_to_holo_alignment.py"

    Components --> ESM2
    Components --> ESMFold
    Components --> USAlign

    %% Model & Training Engine
    subgraph "Model & Training Engine"
        direction TB
        ModelComp["Model Components"]:::model
        LightningMod["LightningModule"]:::model
        Trainer["PyTorch Lightning Trainer"]:::model
    end
    click ModelComp "https://github.com/bioinfomachinelearning/flowdock/tree/main/flowdock/models/components/"
    click LightningMod "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/models/flowdock_fm_module.py"

    Train --> ModelComp
    Train --> LightningMod
    LightningMod --> Trainer

    %% Callbacks & Loggers
    subgraph "Callbacks & Loggers"
        direction TB
        CallbackCfg["Callback Configs"]:::callback
        CallbackCode["EMA Callback"]:::callback
        LoggerCfg["Logger Configs"]:::callback
        Instantiators["Logging Instantiation Helpers"]:::callback
    end
    click CallbackCfg "https://github.com/bioinfomachinelearning/flowdock/tree/main/configs/callbacks/"
    click CallbackCode "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/models/components/callbacks/ema.py"
    click LoggerCfg "https://github.com/bioinfomachinelearning/flowdock/tree/main/configs/logger/"
    click Instantiators "https://github.com/bioinfomachinelearning/flowdock/blob/main/flowdock/utils/instantiators.py"

    Trainer --> CallbackCode
    Trainer --> Instantiators
    Cfg --> CallbackCfg
    Cfg --> LoggerCfg
    CallbackCfg --> CallbackCode
    LoggerCfg --> Instantiators

    %% Utilities
    Utils["Utility Functions"]:::util
    click Utils "https://github.com/bioinfomachinelearning/flowdock/tree/main/flowdock/utils/"

    Train --> Utils
    Eval --> Utils
    Sample --> Utils

    %% Evaluation & Sampling outputs
    Eval -->|"test()"| Trainer
    Trainer --> Metrics["Metrics & Plots"]:::util
    Sample -->|"sampling"| LightningMod
    Sample --> Outputs["Sampled PDB Outputs"]:::util

    %% Storage & Environment
    subgraph "Storage & Environment"
        direction TB
        Checkpoints["Checkpoints"]:::storage
        Docker["Dockerfile"]:::external
    end
    click Docker "https://github.com/bioinfomachinelearning/flowdock/tree/main/Dockerfile"

    Trainer --> Checkpoints
    Sample --> Checkpoints

    %% Styles
    classDef config fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef model fill:#98FB98,stroke:#333,stroke-width:1px
    classDef callback fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef util fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef storage fill:#DCDCDC,stroke:#333,stroke-width:1px
```
