# drugbud-suite/dockm8 architecture

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

- Interactive diagram: https://gitdiagram.com/drugbud-suite/dockm8
- Repository: https://github.com/drugbud-suite/dockm8

## Overview

##### Main Components
- User Interface Layer:
- Streamlit GUI (gui.py, supported by the .streamlit directory)
- Jupyter Notebooks (dockm8.ipynb, dockm8_ensemble.ipynb, dockm8_decoys.ipynb, and various result notebooks)
- Command-line interface via dockm8.py
- Core Workflow/Engine:
- Docking Process Controller: The core logic that handles workflow stages like library and protein preparation, docking, pose selection, rescoring, and ranking.
- Scripts Module: Under the “scripts” directory (includes docking_functions.py, protein_preparation.py, postprocessing.py, utilities.py, etc.) that encapsulate the individual functional components.
- Supporting and Auxiliary Modules:
- Decoy Generation & Consensus Docking: The “software/DeepCoy” submodule that houses an independent tool integrating decoy generation and additional scoring mechanisms.
- Models & Evaluation: The “software/models” folder containing pre-trained models for scoring (RFScore, PLEC, etc.) and evaluation scripts in “software/DeepCoy/evaluation”.
- Deployment & Environment:
- Docker configurations (docker/Dockerfile, docker/environment.yml) for containerized deployments.
- Environment definition files (environment.yml, pyproject.toml) that specify dependencies and technical stack.
- Data Input/Output & Results:
- Input Data: Files under “dockm8_testing” (which include ligand and protein structure files) and “optimal_conditions.txt”.
- Output & Result Analysis: The “results” folder containing Jupyter notebooks that analyze performance and generate plots.
- Media & Documentation: “media” (for logos and images), installation and usage PDFs, and guides.

##### Relationships and Interactions
- At the top, the UI layer where users either interact via the Streamlit web app or trigger the process via command-line / Jupyter environments.
- The UI calls the core workflow engine which orchestrates the various tasks:
▪ Protein and library preparation (invoked from scripts such as protein_preparation.py and library_preparation.py).
▪ Docking execution (scripts/docking_functions.py, consensus methods, clustering functions, etc.).
▪ Postprocessing and scoring (rescoring_functions.py, consensus_methods.py, performance_calculation.py).
- The engine may also optionally integrate the “DeepCoy” module for enhanced decoy generation and evaluation.
- Data flows through these steps: input data (ligands, protein structures, configuration files) → preparation modules → docking execution → consensus scoring → results generation → output into the “results” directory.
- The Docker container encapsulates the entire workflow and environment settings for deployment consistency.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that components (scripts, DeepCoy submodule, model evaluation files) are decoupled enough to allow easy upgrades or replacements.
- Configuration and Environment Management: Highlight the use of configuration files (.streamlit/config.toml, docker/environment.yml) that ensure reproducible setups.
- Extensibility: Noting both the core engine and the “software/DeepCoy” integration shows the readiness for additional modules or plugins in future contributions.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interface Layer
    subgraph "User Interface Layer"
        GUI["Streamlit GUI"]:::ui
        JB1["Jupyter Notebook (dockm8.ipynb)"]:::ui
        JB2["Jupyter Notebook (dockm8_decoys.ipynb)"]:::ui
        JB3["Jupyter Notebook (dockm8_ensemble.ipynb)"]:::ui
        CLI["Command-Line Interface"]:::ui
    end

    %% Core Workflow Engine
    subgraph "Core Workflow Engine"
        CORE["Docking Process Controller & Scripts"]:::engine
        prep["Protein & Library Preparation"]:::engine
        dock["Docking Execution"]:::engine
        score["Pose Rescoring & Consensus"]:::engine
        postproc["Postprocessing"]:::engine
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        DeepCoy["Decoy Generation (DeepCoy)"]:::external
        Models["Models (Pre-trained Scoring)"]:::external
        Evaluate["Evaluation Routines (DeepCoy)"]:::external
    end

    %% Deployment & Environment
    subgraph "Deployment & Environment"
        Docker["Docker Deployment"]:::deployment
        Env["Environment Configurations"]:::deployment
    end

    %% Data Input/Output
    subgraph "Data I/O"
        DataIn["Data Input"]:::data
        Results["Results Output"]:::data
    end

    %% Media & Documentation
    subgraph "Media & Documentation"
        Media["Media & Documentation"]:::docs
    end

    %% Connections between layers
    %% UI Layer to Core Engine
    GUI -->|"triggers"| CORE
    JB1 -->|"triggers"| CORE
    JB2 -->|"triggers"| CORE
    JB3 -->|"triggers"| CORE
    CLI -->|"triggers"| CORE

    %% Data flow from Input to Core Engine
    DataIn -->|"supplies data"| prep

    %% Core Workflow Engine internal flow
    CORE -->|"initiates"| prep
    prep -->|"prepares"| dock
    dock -->|"executes docking"| score
    score -->|"rescoring"| postproc
    postproc -->|"generates"| Results

    %% Integration with Supporting Modules
    CORE -->|"integrates"| DeepCoy
    CORE -->|"integrates"| Models
    CORE -->|"integrates"| Evaluate

    %% Deployment influence (dotted arrows representing environment encapsulation)
    Docker ---|"deploys"| GUI
    Docker ---|"deploys"| CORE
    Env ---|"configures"| CORE

    %% Styles
    classDef ui fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef engine fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef deployment fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef data fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef docs fill:#dda0dd,stroke:#000,stroke-width:2px;

    %% Click Events
    click GUI "https://github.com/drugbud-suite/dockm8/blob/main/gui.py"
    click JB1 "https://github.com/drugbud-suite/dockm8/blob/main/dockm8.ipynb"
    click JB2 "https://github.com/drugbud-suite/dockm8/blob/main/dockm8_decoys.ipynb"
    click JB3 "https://github.com/drugbud-suite/dockm8/blob/main/dockm8_ensemble.ipynb"
    click CLI "https://github.com/drugbud-suite/dockm8/blob/main/dockm8.py"
    click CORE "https://github.com/drugbud-suite/dockm8/blob/main/scripts/docking_functions.py"
    click DeepCoy "https://github.com/drugbud-suite/dockm8/tree/main/software/DeepCoy/"
    click Models "https://github.com/drugbud-suite/dockm8/tree/main/software/models/"
    click Evaluate "https://github.com/drugbud-suite/dockm8/tree/main/software/DeepCoy/evaluation"
    click Docker "https://github.com/drugbud-suite/dockm8/tree/main/docker/"
    click Env "https://github.com/drugbud-suite/dockm8/blob/main/environment.yml"
    click DataIn "https://github.com/drugbud-suite/dockm8/tree/main/dockm8_testing/"
    click Results "https://github.com/drugbud-suite/dockm8/tree/main/results/"
    click Media "https://github.com/drugbud-suite/dockm8/tree/main/media/"
```
