# paiardin/dockingpie architecture

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

- Interactive diagram: https://gitdiagram.com/paiardin/dockingpie
- Repository: https://github.com/paiardin/dockingpie

## Overview

##### Project Type and Purpose
- DockingPie is a desktop plugin for the PyMOL molecular graphics system. It is neither a web service nor a microservice suite, but a full-stack GUI application embedded inside PyMOL.
- Its purpose is to provide a unified front-end for running and comparing multiple molecular docking engines (Smina, AutoDock Vina, RxDock, ADFR) and to perform consensus scoring analyses.

##### File-Structure Analysis
- Top-level “DockingPie1/” directory contains:
- lib/docking_program_main/Functions → core business logic (wrappers for docking engines, I/O, threads, error handling, installer routines)
- lib/docking_program_main/config → static configuration files for each engine
- lib/docking_program_main/docking_program_gui → Qt-based GUI (dialogs, frames, main window, QSS styling)
- lib/docking_program_main/plots → plotting sub-system using pyqtgraph
- lib/docking_program_main/tables → tabular data display
- Key patterns:
- MVC-style separation: GUI layer (Views + Controllers) vs. Functions layer (Services)
- Multithreaded job execution via threads.py/dockings_thread.py
- Plug-in integration into host application (PyMOL API calls via pymol_interactions.py)

##### README Insights
- Plugin is installed via PyMOL’s Plugin Manager and runs inside PyMOL ≥2.3.x
- External tools (RxDock, Vina, Smina, ADFR, OpenBabel, sPyRMSD, sdsorter) are managed by installer routines
- Emphasis on consensus docking: results from multiple engines are aggregated and visualized

##### Main Components
A. Host Environment
- PyMOL application (plugin loader, molecular scene)
B. Plugin Layers
1. GUI Layer (Qt/PyQt)
– MainWindow, Tabs, Dialogs, Frames (docking_program_gui/)
– Event handlers (handle_widgets.py)
2. Controller/Service Layer
– Functions package (adfr_functions, vina_functions, rxdock_functions, smina_functions)
– ConsensusProtocol (consensus_protocol.py)
– Installer & Config Loader (installer.py + config/)
3. Data-Visualization Layer
– Plots via pyqtgraph (plots/…)
– Tables (tables/tables.py)
4. Integration Layer
– PyMOL API interactions (pymol_interactions.py)
5. Concurrency Layer
– Thread management (threads.py, dockings_thread.py)
C. External Dependencies
- Docking executables: Smina, Vina, RxDock, ADFR
- Cheminformatics libraries: OpenBabel, AutoDockTools, sPyRMSD, sdsorter

##### Component Relationships and Data Flow
- User triggers action in GUI → GUI event handler
→ Controller (Functions) prepares inputs (ligand, receptor)
→ Installer/Config modules supply engine-specific parameters
→ Controller dispatches docking jobs to worker threads
→ Each thread invokes external executable (via subprocess call)
→ Raw docking results returned to Controller
→ ConsensusProtocol aggregates and ranks results
→ Visualization modules (pyqtgraph + tables) render plots/tables
→ pymol_interactions updates PyMOL viewport with best poses
- Bi-directional flows:
- GUI ↔ Controller (user inputs & status updates)
- Controller ↔ Worker Threads (job dispatch & result callbacks)
- Controller ↔ External Tools (command-line calls & exit codes)
- Controller → Visualization (data in)
- Visualization → GUI (widgets display)

##### Architectural Patterns & Design Principles
- MVC: clear separation of Views (Qt GUI) from Model/Services (Functions)
- Layered architecture: Presentation, Application Logic, Integration, External
- Concurrency: Thread-per-engine pattern to run docking jobs in parallel
- Plugin architecture: decoupled modules loaded by host (PyMOL)

##### Technologies, Frameworks & Libraries
- Python 3.x
- PyMOL Plugin API
- PyQt5 / Qt Designer (.ui templates, QSS styling)
- pyqtgraph for interactive plotting
- subprocess for external tool invocation
- threading module for concurrency
- config files (text-based) for engine parameters

- Annotation of key cross-cutting concerns (threads, installer)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host Layer
    subgraph "Host Environment" 
        direction TB
        PyMOL["PyMOL Application"]:::host
    end
    click PyMOL "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/__init__.py"

    %% Presentation Layer
    subgraph "Plugin Presentation (GUI)" 
        direction TB
        MainWindow["MainWindow"]:::presentation
        Dialogs["Dialogs"]:::presentation
        Frames["Frames"]:::presentation
        Tabs["Tabs"]:::presentation
        NewWindows["NewWindows"]:::presentation
        QSS["QSS Styling"]:::presentation
        HandleWidgets["Event Handlers"]:::presentation
    end
    click MainWindow "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/main_window.py"
    click Dialogs "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/dialogs.py"
    click Frames "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/frames.py"
    click Tabs "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/tabs.py"
    click NewWindows "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/new_windows.py"
    click QSS "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/docking_program_gui/aqua/aqua.qss"
    click HandleWidgets "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/handle_widgets.py"

    %% Services Layer
    subgraph "Plugin Services (Controllers/Business Logic)"
        direction TB
        SminaFunc["smina_functions.py"]:::services
        VinaFunc["vina_functions.py"]:::services
        RxDockFunc["rxdock_functions.py"]:::services
        ADFRFunc["adfr_functions.py"]:::services
        Consensus["consensus_protocol.py"]:::services
        GenDock["general_docking_func.py"]:::services
        GenFuncs["general_functions.py"]:::services
        Exceptions["exceptions.py"]:::services
    end
    click SminaFunc "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/smina_functions.py"
    click VinaFunc "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/vina_functions.py"
    click RxDockFunc "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/rxdock_functions.py"
    click ADFRFunc "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/adfr_functions.py"
    click Consensus "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/consensus_protocol.py"
    click GenDock "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/general_docking_func.py"
    click GenFuncs "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/general_functions.py"
    click Exceptions "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/exceptions.py"

    %% Installer & Config
    subgraph "Installer & Config Loader" 
        direction TB
        Installer["installer.py"]:::services
        ConfigStore[(Engine Config Files)]:::services
    end
    click Installer "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/installer.py"
    click ConfigStore "https://github.com/paiardin/dockingpie/tree/main/DockingPie1/lib/docking_program_main/config/"

    %% Visualization Layer
    subgraph "Data Visualization" 
        direction TB
        Plots["Plots Window"]:::visualization
        Tables["Tables Display"]:::visualization
        PyQtGraph["pyqtgraph Library"]:::visualization
    end
    click Plots "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/plots/plots_window.py"
    click Tables "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/tables/tables.py"

    %% Integration Layer
    subgraph "Integration Layer" 
        direction TB
        PymolInt["pymol_interactions.py"]:::integration
    end
    click PymolInt "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/pymol_interactions.py"

    %% Concurrency Layer
    subgraph "Concurrency Layer" 
        direction TB
        Threads["threads.py"]:::concurrency
        DockingThread["dockings_thread.py"]:::concurrency
    end
    click Threads "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/threads.py"
    click DockingThread "https://github.com/paiardin/dockingpie/blob/main/DockingPie1/lib/docking_program_main/Functions/dockings_thread.py"

    %% External Dependencies
    subgraph "External Tools & Libraries" 
        direction TB
        SminaCloud(["Smina"]):::external
        VinaCloud(["AutoDock Vina"]):::external
        RxDockCloud(["RxDock"]):::external
        ADFRCloud(["ADFR"]):::external
        OpenBabel(["OpenBabel"]):::external
        ADTools(["AutoDockTools"]):::external
        SPRMSD(["sPyRMSD"]):::external
        SDSorter(["sdsorter"]):::external
    end

    %% Data Flows
    PyMOL -->|loads plugin| MainWindow
    MainWindow -->|user action| HandleWidgets
    HandleWidgets -->|calls| SminaFunc
    HandleWidgets -->|calls| VinaFunc
    HandleWidgets -->|calls| RxDockFunc
    HandleWidgets -->|calls| ADFRFunc
    SminaFunc -->|uses| Installer
    VinaFunc -->|uses| Installer
    RxDockFunc -->|uses| Installer
    ADFRFunc -->|uses| Installer
    Installer -.->|reads configs| ConfigStore
    SminaFunc -->|dispatch| Threads
    VinaFunc -->|dispatch| Threads
    RxDockFunc -->|dispatch| Threads
    ADFRFunc -->|dispatch| Threads
    Threads -->|spawn| DockingThread
    DockingThread -->|executes| SminaCloud
    DockingThread -->|executes| VinaCloud
    DockingThread -->|executes| RxDockCloud
    DockingThread -->|executes| ADFRCloud
    SminaCloud -->|returns results| DockingThread
    VinaCloud -->|returns results| DockingThread
    RxDockCloud -->|returns results| DockingThread
    ADFRCloud -->|returns results| DockingThread
    DockingThread -->|callback| GenDock
    GenDock -->|errors| Exceptions
    GenDock -->|normalizes| Consensus
    Consensus -->|aggregates| Plots
    Consensus -->|aggregates| Tables
    Plots -->|render| MainWindow
    Tables -->|render| MainWindow
    Consensus -->|sends poses| PymolInt
    PymolInt -->|updates view| PyMOL

    %% Styles
    classDef host fill:#D0E1F9,stroke:#0366D6,color:#0366D6;
    classDef presentation fill:#D6EFD6,stroke:#28A745,color:#155724;
    classDef services fill:#FFF3CD,stroke:#FFC107,color:#856404;
    classDef visualization fill:#FDE2E4,stroke:#DC3545,color:#721C24;
    classDef integration fill:#E2E3E5,stroke:#6C757D,color:#343A40;
    classDef concurrency fill:#E8DAEF,stroke:#6F42C1,color:#4E2A84;
    classDef external fill:#CCE5FF,stroke:#0056B3,color:#004085;
```
