# maurobedoya/gatewizard architecture

> Architecture diagram of the GitHub repository maurobedoya/gatewizard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maurobedoya/gatewizard
- Repository: https://github.com/maurobedoya/gatewizard

## Overview

1. **What this repo is**
   GateWizard is a Python package plus desktop GUI for membrane-protein preparation and MD equilibration/analysis. The architecture is centered on turning one or more structural inputs, usually PDB-based, into prepared systems, simulation inputs, and post-run analyses.

2. **Top-level runtime entrypoint**
   The main application entrypoint is `gatewizard/main.py`. The package is organized so the GUI and command-line launch both route into the same core workflows rather than having separate business logic paths.

3. **Core orchestration layer**
   `gatewizard/core/` is the main application backbone. It contains:
   - `builder.py` for assembling the prepared system from components
   - `preparation.py` for protein cleanup and preprocessing
   - `structure_manager.py` for structure inspection/manipulation
   - `mempro.py` for membrane-protein orientation and membrane-related setup
   - `file_manager.py` for managing generated artifacts and project folders
   - `job_monitor.py` for tracking long-running external jobs and status updates  
   This is the layer the GUI and tools call into.

4. **Feature-specific tool layer**
   `gatewizard/tools/` exposes higher-level workflows:
   - `force_fields.py` for force-field related choices/mapping
   - `ligand_parametrization.py` for ligand parameter generation
   - `equilibration.py` for simulation protocol setup
   - `validators.py` for input and state validation  
   This layer appears to wrap or coordinate the core modules for user-facing operations.

5. **Preparation pipeline**
   The preparation flow is likely: raw protein structure in -> clean/repair structure -> cap termini if needed -> assign protonation states -> generate prepared protein ready for membrane or ligand workflows. Supporting utilities in `gatewizard/utils/protein_capping.py`, `gatewizard/utils/helpers.py`, and `gatewizard/utils/config.py` indicate that this stage is opinionated and parameterized.

6. **Membrane-system construction**
   Membrane-related functionality is a distinct boundary. The repo contains `gatewizard/utils/bilayer_utils.py` and a dedicated `mempro` integration, indicating a workflow that orients the protein, builds/places the bilayer, and prepares the combined membrane-protein system. The test fixtures under `tests/equilibration_examples/popc_membrane/` show the output of this stage: prepared PDBs, topology files, logs, and status metadata.

7. **Equilibration backends**
   The `equilibration/` directory is a library of static protocol templates and scripts for multiple engines:
   - **GROMACS**: `.mdp` protocol files
   - **NAMD**: `.inp` configuration templates
   - **OpenMM**: `.inp` templates plus Python helper scripts in `equilibration/openmm/scripts/`  
   This suggests the equilibration subsystem is template-driven: the app generates engine-specific run inputs and then hands execution to the external simulator.

8. **Simulation support scripts**
   OpenMM has extra implementation support in `equilibration/openmm/scripts/`:
   - reading inputs/parameters
   - barostat configuration
   - restraints
   - rewrapping
   - virtual force-switch handling
   - a runnable `openmm_run.py`  
   These scripts are part of the runtime boundary between GateWizard’s generated protocols and the simulator execution environment.

9. **Analysis subsystem**
   `gatewizard/utils/analysis`-style modules are split by engine:
   - `gromacs_analysis.py`
   - `namd_analysis.py`
   - `openmm_analysis.py`  
   The `tests/analysis_examples/` directory contains many end-to-end example scripts and saved outputs, which implies the analysis layer consumes trajectories/logs from each engine and produces summaries or plots with MDAnalysis/Matplotlib-style tooling.

10. **External scientific dependencies**
    The architecture depends on several external tools that materially shape the flow:
    - **AmberTools / Parmed** for topology and structure preparation
    - **Propka** for pKa/protonation assignment
    - **MemPrO** for membrane protein orientation
    - **NAMD**, **GROMACS**, and **OpenMM** as execution backends
    - **RDKit** and **MDAnalysis** for chemistry/trajectory support  
    These are not just libraries; they define the boundaries between internal orchestration and external scientific computation.

11. **State, artifacts, and job tracking**
    The repo stores many intermediate and final artifacts on disk rather than in memory: prepared PDBs, prmtop/inpcrd files, restraint files, protocol summaries, logs, and status JSON. That implies the architecture is file-centric and workflow-oriented, with `file_manager` and `job_monitor` coordinating progress across stages.

12. **Documentation, release, and validation**
    `docs/` is a full MkDocs documentation site, while `.github/workflows/` automates releases, docs deployment, and PyPI publishing. `tests/` contains both unit tests and extensive fixture-based example workflows, which mirrors the real pipeline structure and is useful for validating architecture around each stage boundary.

Main entry points: [`gatewizard/core/builder.py`](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/builder.py) (Builder), [`gatewizard/tools/equilibration.py`](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/equilibration.py) (Equilibration), [`tests`](https://github.com/maurobedoya/gatewizard/tree/main/tests) (Examples), [`gatewizard/core/preparation.py`](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/preparation.py) (Preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App"]
  node_gatewizard_main["Main app<br/>entrypoint<br/>[main.py]"]
end

subgraph group_group_core["Core"]
  node_core_builder["Builder<br/>orchestrator<br/>[builder.py]"]
  node_core_preparation["Preparation<br/>pipeline stage<br/>[preparation.py]"]
  node_core_structure["Structure mgmt<br/>structure service"]
  node_core_mempro["MemPro bridge<br/>membrane setup<br/>[mempro.py]"]
  node_core_files["File manager<br/>artifact manager<br/>[file_manager.py]"]
  node_core_jobs["Job monitor<br/>status tracker<br/>[job_monitor.py]"]
end

subgraph group_group_tools["Tools"]
  node_tool_equil["Equilibration<br/>workflow tool<br/>[equilibration.py]"]
  node_tool_ff["Force fields<br/>mapping tool<br/>[force_fields.py]"]
  node_tool_ligand["Ligand prep<br/>parameterization tool"]
  node_tool_validators["Validators<br/>validation layer<br/>[validators.py]"]
end

subgraph group_group_utils["Utils"]
  node_utils_capping["Capping<br/>protein utility<br/>[protein_capping.py]"]
  node_utils_config["Config<br/>settings<br/>[config.py]"]
  node_utils_helpers["Helpers<br/>[helpers.py]"]
  node_utils_bilayer["Bilayer utils<br/>membrane utility<br/>[bilayer_utils.py]"]
  node_utils_analysis["Analysis"]
end

subgraph group_group_eq["Equilibration"]
  node_eq_templates["Protocol templates<br/>template library"]
  node_eq_openmm_scripts["OpenMM scripts<br/>runtime scripts"]
end

subgraph group_group_docs["Docs"]
  node_docs_site["Docs site<br/>documentation"]
end

subgraph group_group_ci["CI"]
  node_ci_workflows["GitHub Actions<br/>automation<br/>[workflows]"]
end

subgraph group_group_tests["Tests"]
  node_tests_examples["Examples<br/>fixtures"]
end

node_gatewizard_main -->|"launches"| node_core_builder
node_gatewizard_main -->|"exposes"| node_tool_equil
node_core_builder -->|"uses"| node_core_preparation
node_core_builder -->|"uses"| node_core_structure
node_core_builder -->|"uses"| node_core_mempro
node_core_builder -->|"writes"| node_core_files
node_core_builder -->|"tracks"| node_core_jobs
node_tool_equil -->|"selects"| node_tool_ff
node_tool_equil -->|"coordinates"| node_tool_ligand
node_tool_equil -->|"checks"| node_tool_validators
node_tool_equil -->|"renders"| node_eq_templates
node_tool_equil -->|"generates"| node_eq_openmm_scripts
node_core_preparation -->|"calls"| node_utils_capping
node_core_preparation -->|"reads"| node_utils_config
node_core_preparation -->|"uses"| node_utils_helpers
node_core_mempro -->|"uses"| node_utils_bilayer
node_core_mempro -->|"stores"| node_core_files
node_utils_analysis -.->|"consumes"| node_eq_templates
node_docs_site -.->|"documents"| node_gatewizard_main
node_ci_workflows -.->|"deploys"| node_docs_site
node_ci_workflows -.->|"releases"| node_gatewizard_main
node_tests_examples -.->|"validates"| node_core_builder
node_tests_examples -.->|"validates"| node_tool_equil
node_tests_examples -.->|"validates"| node_utils_analysis
node_tests_examples -.->|"validates"| node_core_mempro

click node_gatewizard_main "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/main.py"
click node_core_builder "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/builder.py"
click node_core_preparation "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/preparation.py"
click node_core_structure "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/structure_manager.py"
click node_core_mempro "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/mempro.py"
click node_core_files "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/file_manager.py"
click node_core_jobs "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/job_monitor.py"
click node_tool_equil "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/equilibration.py"
click node_tool_ff "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/force_fields.py"
click node_tool_ligand "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/ligand_parametrization.py"
click node_tool_validators "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/validators.py"
click node_utils_capping "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/protein_capping.py"
click node_utils_config "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/config.py"
click node_utils_helpers "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/helpers.py"
click node_utils_bilayer "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/bilayer_utils.py"
click node_utils_analysis "https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/gromacs_analysis.py"
click node_eq_templates "https://github.com/maurobedoya/gatewizard/tree/main/equilibration"
click node_eq_openmm_scripts "https://github.com/maurobedoya/gatewizard/tree/main/equilibration/openmm/scripts"
click node_docs_site "https://github.com/maurobedoya/gatewizard/tree/main/docs"
click node_ci_workflows "https://github.com/maurobedoya/gatewizard/blob/main/.github/workflows"
click node_tests_examples "https://github.com/maurobedoya/gatewizard/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gatewizard_main,node_ci_workflows toneBlue
class node_core_builder,node_core_preparation,node_core_structure,node_core_mempro,node_core_files,node_core_jobs,node_tests_examples toneAmber
class node_tool_equil,node_tool_ff,node_tool_ligand,node_tool_validators toneMint
class node_utils_capping,node_utils_config,node_utils_helpers,node_utils_bilayer,node_utils_analysis toneRose
class node_eq_templates,node_eq_openmm_scripts toneIndigo
class node_docs_site toneTeal
```

## Components

### App

User entrypoints and orchestration

- [Main app](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/main.py): entrypoint · Desktop/CLI launch path that enters the package workflows · `gatewizard/main.py`

### Core

System preparation and workflow coordination

- [Builder](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/builder.py): orchestrator · Assembles prepared systems from structure, membrane, and ligands · `gatewizard/core/builder.py`
- [Preparation](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/preparation.py): pipeline stage · Protein cleanup, repair, protonation, and prep logic · `gatewizard/core/preparation.py`
- [Structure mgmt](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/structure_manager.py): structure service · Inspection and manipulation of structural inputs · `gatewizard/core/structure_manager.py`
- [MemPro bridge](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/mempro.py): membrane setup · Membrane-protein orientation and membrane setup integration · `gatewizard/core/mempro.py`
- [File manager](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/file_manager.py): artifact manager · Project folders and generated artifact handling · `gatewizard/core/file_manager.py`
- [Job monitor](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/core/job_monitor.py): status tracker · Tracks long-running external jobs and status updates · `gatewizard/core/job_monitor.py`

### Tools

User-facing workflow helpers

- [Equilibration](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/equilibration.py): workflow tool · Builds engine-specific simulation protocols · `gatewizard/tools/equilibration.py`
- [Force fields](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/force_fields.py): mapping tool · Force-field selection and mapping support · `gatewizard/tools/force_fields.py`
- [Ligand prep](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/ligand_parametrization.py): parameterization tool · Generates ligand parameters for downstream workflows · `gatewizard/tools/ligand_parametrization.py`
- [Validators](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/tools/validators.py): validation layer · Input and state validation for user-facing workflows · `gatewizard/tools/validators.py`

### Utils

Shared scientific helpers and analysis

- [Capping](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/protein_capping.py): protein utility · Terminal capping and protein-specific preparation helpers · `gatewizard/utils/protein_capping.py`
- [Config](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/config.py): settings · Central configuration and runtime options · `gatewizard/utils/config.py`
- [Helpers](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/helpers.py): shared helpers · Common utility functions used across workflows · `gatewizard/utils/helpers.py`
- [Bilayer utils](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/bilayer_utils.py): membrane utility · Membrane/bilayer construction helpers · `gatewizard/utils/bilayer_utils.py`
- [Analysis](https://github.com/maurobedoya/gatewizard/blob/main/gatewizard/utils/gromacs_analysis.py): analysis module · Engine-specific trajectory and log analysis helpers · `gatewizard/utils/gromacs_analysis.py`

### Equilibration

Engine-specific protocol templates and scripts

- [Protocol templates](https://github.com/maurobedoya/gatewizard/tree/main/equilibration): template library · Static equilibration inputs for GROMACS, NAMD, and OpenMM · `equilibration`
- [OpenMM scripts](https://github.com/maurobedoya/gatewizard/tree/main/equilibration/openmm/scripts): runtime scripts · OpenMM runtime helpers for reading inputs, restraints, and execution · `equilibration/openmm/scripts`

### Docs

Documentation and site config

- [Docs site](https://github.com/maurobedoya/gatewizard/tree/main/docs): documentation · MkDocs documentation and API references · `docs`

### CI

Release and publishing automation

- [GitHub Actions](https://github.com/maurobedoya/gatewizard/blob/main/.github/workflows): automation · Release, docs deployment, and PyPI publishing workflows · `.github/workflows`

### Tests

Example workflows and fixtures

- [Examples](https://github.com/maurobedoya/gatewizard/tree/main/tests): fixtures · End-to-end example workflows and saved outputs for validation · `tests`

## Connections

- Main app → Builder: launches · Application entrypoint routes into core orchestration
- Main app → Equilibration: exposes · Main app surfaces user-facing equilibration workflow
- Builder → Preparation: uses · Builder coordinates protein preparation steps
- Builder → Structure mgmt: uses · Builder depends on structural inspection and editing
- Builder → MemPro bridge: uses · Builder integrates membrane-protein setup when needed
- Builder → File manager: writes · Prepared systems and artifacts are persisted to project folders
- Builder → Job monitor: tracks · Long-running stages report status and progress
- Equilibration → Force fields: selects · Equilibration workflows depend on force-field decisions
- Equilibration → Ligand prep: coordinates · Ligand parameterization feeds the equilibration setup
- Equilibration → Validators: checks · Workflow inputs and state are validated before generation
- Equilibration → Protocol templates: renders · Protocol templates are materialized into runnable inputs
- Equilibration → OpenMM scripts: generates · OpenMM workflows use helper scripts at the runtime boundary
- Preparation → Capping: calls · Protein cleanup can cap termini and related endpoints
- Preparation → Config: reads · Preparation behavior is parameterized by configuration
- Preparation → Helpers: uses · Shared helpers support cleanup and prep logic
- MemPro bridge → Bilayer utils: uses · Membrane workflows use bilayer construction helpers
- MemPro bridge → File manager: stores · Membrane preparation artifacts are written to disk
- Analysis → Protocol templates: consumes · Analysis operates on outputs from engine-specific equilibration runs
- Docs site → Main app: documents · Docs explain the application entrypoint and workflows
- GitHub Actions → Docs site: deploys · Workflow publishes the documentation site
- GitHub Actions → Main app: releases · Workflow automates package release and publishing
- Examples → Builder: validates · Builder examples mirror system-preparation flows
- Examples → Equilibration: validates · Equilibration examples capture template-driven protocol generation
- Examples → Analysis: validates · Analysis examples exercise engine-specific post-processing
- Examples → MemPro bridge: validates · Membrane examples cover orientation and bilayer setup
