# jule-c/flowr architecture

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

- Interactive diagram: https://gitdiagram.com/jule-c/flowr
- Repository: https://github.com/jule-c/flowr

## Overview

##### Project type and purpose
- This is a Python-based research toolkit (no GUI/frontend) for structure-aware, flow-matching ligand generation. It provides a full CLI-driven pipeline: data ingestion & preprocessing, model definition & training, de novo/fragment-based generation, and multi-facet evaluation.

##### File structure analysis
- Top-level directories:
- flowr/        ← core library: data, models, training, generation, evaluation, utilities
- genbench3d/   ← 3D geometry & scoring backend (data sources, geometry extraction, scoring metrics)
- posebusters/  ← docking-based error modules, CLI, configs, dataset loaders, scoring modules
- posecheck/    ← independent pose quality checks & utilities
- callbacks/    ← training callbacks (e.g., EMA, prediction logging)
- scripts/      ← SLURM/batch scripts for train, generate, evaluate
- Key files:
- environment.yml       ← conda dependencies
- genbench3d/config/*.yaml ← geometry tool config
- posebusters/config/*.yml ← docking & generation config
- README.md             ← project overview & workflow instructions

##### README insights
- Full FLOWR workflow: setup → data download → train → generate → evaluate
- External dependencies: ADFR suite, SLURM scheduler, Python packages (RDKit, PyTorch, etc.)
- Examples of CLI/SLURM scripts for automation

##### Components & interactions
1. Data Layer
- Raw SPINDR data (.smol, .cif), genbench3d_data, posebusters PDB library
- Preprocessing modules: flowr/data, genbench3d/data, posebusters/datasets
2. Model Layer
- Model definitions: flowr/models (EGNN, EQGAT, SEMLA…)
- Callbacks (callbacks/)
3. Training Pipeline
- Trainer entrypoint: flowr/train.py
- Datamodule: flowr/data/datamodules.py
- Scripts: scripts/train_spindr.sh → SLURM
4. Generation Pipeline
- FLOWR generation: flowr/gen/predict*.py
- genbench3d generation: genbench3d/genbench3d.py / sbgenbench3d.py
- posebusters CLI: posebusters/cli.py & modules → error modules
- Scripts: scripts/gen_spindr.sl, gen_pdb.sl
5. Evaluation Pipeline
- FLOWR evaluation: flowr/eval/*
- genbench3d metrics: genbench3d/metrics/*
- posebusters scoring & posecheck: posebusters/modules & posecheck/eval.py
- Scripts: scripts/eval_spindr.sh
6. Utilities & Config
- Shared utilities: flowr/util, genbench3d/utils, posebusters/tools, posecheck/utils
- Configuration files: environment.yml, YAML under genbench3d/config & posebusters/config
7. External Services
- ADFR docking engine
- SLURM scheduler
- Zenodo dataset repository

- “Raw Data” → Preprocessing → Processed Datasets → DataLoader → Training
- Training → Model Checkpoint → Generation
- Model Checkpoint + Input (pocket .pdb/.cif + optional fragments) → Generation → SDF output
- Generated SDFs → Evaluation modules → Metrics report
- Posebusters & Posecheck can plug in at Generation/Evaluation stages for alternative scoring

c. Architectural patterns & principles
- Modular Python packages separated by responsibility (data / models / pipeline / utilities)
- CLI + SLURM scripts orchestrate end-to-end workflows
- Configuration as code (YAML files) for reproducibility
- Callbacks for extensibility (logging, EMA, checkpointing)
- Reuse of shared utilities across sub-projects

d. Key technologies & libraries
- PyTorch (implied via datamodules, callbacks)
- RDKit, Biopython for cheminformatics/structural tasks
- ADFR for docking
- SLURM for job scheduling
- YAML for config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        flowr_data["flowr/data"]:::data
        gen3d_data["genbench3d/data"]:::data
        poseb_data["posebusters/datasets"]:::data
        posecheck_data["posecheck/data"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        flowr_models["flowr/models"]:::model
        callbacks["callbacks"]:::model
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        datamodule["flowr/data/datamodules.py"]:::training
        train_py["flowr/train.py"]:::training
        train_script["scripts/train_spindr.sh"]:::training
        checkpoint["Model Checkpoint"]:::storage
    end

    %% Generation Pipeline
    subgraph "Generation Pipeline"
        direction TB
        flowr_gen["flowr/gen"]:::gen
        gen3d_gen["genbench3d/genbench3d.py"]:::gen
        gen3d_sb["genbench3d/sbgenbench3d.py"]:::gen
        poseb_cli["posebusters/cli.py"]:::gen
        poseb_mod["posebusters/modules"]:::gen
        gen_script1["scripts/gen_spindr.sl"]:::gen
        gen_script2["scripts/gen_pdb.sl"]:::gen
        pocket_input["Pocket (PDB/CIF)+Fragments"]:::external
        sdf_output["Generated SDFs"]:::storage
    end

    %% Evaluation Pipeline
    subgraph "Evaluation Pipeline"
        direction TB
        flowr_eval["flowr/eval"]:::eval
        gen3d_metrics["genbench3d/metrics"]:::eval
        poseb_score["posebusters/modules"]:::eval
        posecheck_eval["posecheck/eval.py"]:::eval
        eval_script["scripts/eval_spindr.sh"]:::eval
        report["Metrics Report"]:::storage
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        direction TB
        flowr_util["flowr/util"]:::util
        gen3d_util["genbench3d/utils"]:::util
        poseb_util["posebusters/tools"]:::util
        posecheck_util["posecheck/utils"]:::util
        env_yml["environment.yml"]:::config
        gen3d_cfg["genbench3d/config/default.yaml"]:::config
        poseb_cfg1["posebusters/config/dock.yml"]:::config
        poseb_cfg2["posebusters/config/gen.yml"]:::config
        poseb_cfg3["posebusters/config/mol.yml"]:::config
        poseb_cfg4["posebusters/config/redock.yml"]:::config
    end

    %% External Dependencies & Orchestration
    subgraph "External"
        direction TB
        zenodo["Zenodo Repository"]:::external
        adfr["ADFR Docking Engine"]:::external
        slurm["SLURM Scheduler"]:::external
    end

    %% Data Flow
    zenodo -->|provides raw data| flowr_data
    zenodo -->|provides raw data| gen3d_data
    zenodo -->|provides raw data| poseb_data
    flowr_data -->|"loads"| datamodule
    gen3d_data -->|"loads"| datamodule
    poseb_data -->|"loads"| datamodule
    posecheck_data -->|"loads"| datamodule

    datamodule -->|"feeds data"| train_py
    train_py -->|"saves checkpoint"| checkpoint
    checkpoint -->|"used by"| flowr_gen

    pocket_input -->|"input to"| flowr_gen
    flowr_gen -->|"outputs SDFs"| sdf_output

    sdf_output -->|"evaluated by"| flowr_eval
    sdf_output -->|"evaluated by"| gen3d_metrics
    sdf_output -->|"evaluated by"| poseb_score
    sdf_output -->|"evaluated by"| posecheck_eval

    flowr_eval -->|"generates"| report
    gen3d_metrics -->|"generates"| report
    poseb_score -->|"generates"| report
    posecheck_eval -->|"generates"| report

    %% Control/Orchestration
    slurm -.-> train_script
    slurm -.-> gen_script1
    slurm -.-> gen_script2
    slurm -.-> eval_script

    train_script --> train_py
    gen_script1 --> flowr_gen
    gen_script2 --> gen3d_gen
    eval_script --> flowr_eval

    %% External tool integration
    adfr --> poseb_score
    adfr --> posecheck_eval

    %% Config & Utilities links
    env_yml -.-> train_py
    gen3d_cfg -.-> gen3d_gen
    poseb_cfg1 -.-> poseb_cli
    poseb_cfg2 -.-> poseb_cli
    poseb_cfg3 -.-> poseb_cli
    poseb_cfg4 -.-> poseb_cli

    flowr_util -.-> flowr_models
    gen3d_util -.-> gen3d_gen
    poseb_util -.-> poseb_cli
    posecheck_util -.-> posecheck_eval

    %% Click Events
    click flowr_data "https://github.com/jule-c/flowr/tree/main/flowr/data/"
    click gen3d_data "https://github.com/jule-c/flowr/tree/main/genbench3d/data/"
    click poseb_data "https://github.com/jule-c/flowr/tree/main/posebusters/datasets/"
    click posecheck_data "https://github.com/jule-c/flowr/tree/main/posecheck/data/"

    click flowr_models "https://github.com/jule-c/flowr/tree/main/flowr/models/"
    click callbacks "https://github.com/jule-c/flowr/tree/main/callbacks/"

    click datamodule "https://github.com/jule-c/flowr/blob/main/flowr/data/datamodules.py"
    click train_py "https://github.com/jule-c/flowr/blob/main/flowr/train.py"
    click train_script "https://github.com/jule-c/flowr/blob/main/scripts/train_spindr.sh"

    click flowr_gen "https://github.com/jule-c/flowr/tree/main/flowr/gen/"
    click gen3d_gen "https://github.com/jule-c/flowr/blob/main/genbench3d/genbench3d.py"
    click gen3d_sb "https://github.com/jule-c/flowr/blob/main/genbench3d/sbgenbench3d.py"
    click poseb_cli "https://github.com/jule-c/flowr/blob/main/posebusters/cli.py"
    click poseb_mod "https://github.com/jule-c/flowr/tree/main/posebusters/modules/"
    click gen_script1 "https://github.com/jule-c/flowr/blob/main/scripts/gen_spindr.sl"
    click gen_script2 "https://github.com/jule-c/flowr/blob/main/scripts/gen_pdb.sl"

    click flowr_eval "https://github.com/jule-c/flowr/tree/main/flowr/eval/"
    click gen3d_metrics "https://github.com/jule-c/flowr/tree/main/genbench3d/metrics/"
    click poseb_score "https://github.com/jule-c/flowr/tree/main/posebusters/modules/"
    click posecheck_eval "https://github.com/jule-c/flowr/blob/main/posecheck/eval.py"
    click eval_script "https://github.com/jule-c/flowr/blob/main/scripts/eval_spindr.sh"

    click flowr_util "https://github.com/jule-c/flowr/tree/main/flowr/util/"
    click gen3d_util "https://github.com/jule-c/flowr/tree/main/genbench3d/utils/"
    click poseb_util "https://github.com/jule-c/flowr/tree/main/posebusters/tools/"
    click posecheck_util "https://github.com/jule-c/flowr/tree/main/posecheck/utils/"
    click env_yml "https://github.com/jule-c/flowr/blob/main/environment.yml"
    click gen3d_cfg "https://github.com/jule-c/flowr/blob/main/genbench3d/config/default.yaml"
    click poseb_cfg1 "https://github.com/jule-c/flowr/blob/main/posebusters/config/dock.yml"
    click poseb_cfg2 "https://github.com/jule-c/flowr/blob/main/posebusters/config/gen.yml"
    click poseb_cfg3 "https://github.com/jule-c/flowr/blob/main/posebusters/config/mol.yml"
    click poseb_cfg4 "https://github.com/jule-c/flowr/blob/main/posebusters/config/redock.yml"

    %% Styling
    classDef data fill:#e6ffe6,stroke:#2d8f2d
    classDef model fill:#e6f0ff,stroke:#2a5caa
    classDef training fill:#e0f7fa,stroke:#007c91
    classDef gen fill:#fff3e0,stroke:#ff8f00
    classDef eval fill:#f3e5f5,stroke:#8e24aa
    classDef util fill:#f5f5f5,stroke:#9e9e9e
    classDef config fill:#f5f5f5,stroke:#616161,stroke-dasharray: 2 2
    classDef storage fill:#ffffff,stroke:#000000,stroke-dasharray: 4 2
    classDef external fill:#ffffff,stroke:#000000,stroke-dasharray: 2 2, color:#555555
```
