# openmm/pdbfixer architecture

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

- Interactive diagram: https://gitdiagram.com/openmm/pdbfixer
- Repository: https://github.com/openmm/pdbfixer

## Overview

##### Project type and purpose
- PDBFixer is a Python-based utility for preparing PDB (Protein Data Bank) files for molecular simulation.
- It provides both a command-line interface (CLI) and a browser-based UI (via a lightweight Python HTTP server).
- It bundles core “fixer” functionality (adding atoms, building loops, deleting chains, etc.), templates, tests, packaging scripts, and CI tooling.

##### Main architectural components
a. User Interfaces
– CLI front end (pdbfixer/cli entry points in setup.py, ui.py)
– Browser UI served by uiserver.py + HTML templates (pdbfixer/html & templates)
b. Core Engine
– pdbfixer/pdbfixer.py: the Python library implementing all “fixer” operations
– soft.xml forcefield data
– pdb templates under pdbfixer/templates
c. Data Layer
– Input PDB files (user-supplied or test fixtures)
– Output PDB files
d. Packaging & Distribution
– setup.py / setup.cfg
– devtools/conda-recipe (meta.yaml, build.sh)
– environment-dev.yaml for dev environment
e. Continuous Integration & Deployment
– GitHub Actions workflow (.github/workflows/CI.yml)
– Travis CI config (.travis.yml, devtools/travis-ci scripts)
– docs publication (push-docs-to-s3.py)

##### Relationships & data flow
- User invokes either:
– CLI: `pdbfixer …` → loads core engine → reads input PDB → performs fixes → writes output
– Browser UI: launch uiserver.py → serves HTML pages → user clicks actions → server calls core engine → returns updated PDB or progress page
- Core engine uses:
– XML forcefield (soft.xml)
– Residue templates (templates/*.pdb)
- Packaging tools consume the source tree to build conda packages or PyPI distributions.
- CI workflows run tests (pdbfixer/tests) and deployment scripts on each push.

##### Architectural patterns & design principles
- Separation of concerns:
– UI layer (CLI vs HTTP) is thin, delegates logic to the core engine.
– Core engine is a pure Python library with no UI dependencies.
- Modular data definitions:
– Templates and XML forcefield are external data resources.
- Test isolation:
– Unit tests operate directly on core functions using test PDB fixtures.

##### Elements
– Clear component names: “PDBFixer Core Library,” “CLI Front End,” “Browser UI Server,” “Templates & Forcefield Data,” “Conda-Package Builder,” “CI/CD Pipelines.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLIFront["CLI Front End"]:::ui
        BrowserUI["Browser UI Server"]:::ui
    end

    %% Core Engine
    Core["PDBFixer Core Library"]:::code

    %% Data Resources
    subgraph "Data Resources"
        InputPDB["Input PDB Files"]:::data
        OutputPDB["Output PDB Files"]:::data
        Forcefield["Forcefield Data (soft.xml)"]:::data
        ResidueTemplates["Residue Templates"]:::data
        HTMLTemplates["HTML Templates"]:::data
        UIAssets["UI Assets"]:::data
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        SetupPy["setup.py"]:::code
        SetupCfg["setup.cfg"]:::code
        CondaMeta["meta.yaml"]:::code
        CondaBuild["build.sh"]:::code
        EnvSpec["environment-dev.yaml"]:::code
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        GHActions["GitHub Actions CI"]:::external
        TravisConfig["Travis CI"]:::external
        TravisScripts["CI Scripts"]:::external
        DocsScript["Docs Publishing Script"]:::external
        UnitTests["Unit Tests"]:::code
    end

    %% Documentation
    subgraph "Documentation"
        Manual["Manual/User Guide"]:::external
        Readme["README.md"]:::external
    end

    %% Relationships
    CLIFront -->|"invokes Core"| Core
    BrowserUI -->|"serves HTML & calls Core"| Core

    Core -->|"reads input PDB"| InputPDB
    Core -->|"writes output PDB"| OutputPDB
    Core -->|"uses forcefield data"| Forcefield
    Core -->|"uses residue templates"| ResidueTemplates

    BrowserUI -->|"serves pages"| HTMLTemplates
    BrowserUI -->|"serves assets"| UIAssets

    SetupPy -->|"defines package"| Core
    SetupPy --> Manual
    SetupPy --> Readme
    SetupPy --> SetupCfg
    CondaMeta -->|"build recipe"| Core
    CondaBuild --> CondaMeta
    EnvSpec -->|"dev environment spec"| SetupPy

    TravisConfig -->|"runs tests"| UnitTests
    GHActions -->|"runs tests"| UnitTests
    TravisScripts -->|"after success"| DocsScript
    DocsScript -->|"publishes docs to S3"| GHActions

    %% Click Events
    click CLIFront "https://github.com/openmm/pdbfixer/blob/master/pdbfixer/ui.py"
    click BrowserUI "https://github.com/openmm/pdbfixer/blob/master/pdbfixer/uiserver.py"
    click HTMLTemplates "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/html/"
    click UIAssets "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/images/"
    click Core "https://github.com/openmm/pdbfixer/blob/master/pdbfixer/pdbfixer.py"
    click Forcefield "https://github.com/openmm/pdbfixer/blob/master/pdbfixer/soft.xml"
    click ResidueTemplates "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/templates/"
    click InputPDB "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/tests/data/"
    click OutputPDB "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/tests/data/"
    click SetupPy "https://github.com/openmm/pdbfixer/blob/master/setup.py"
    click SetupCfg "https://github.com/openmm/pdbfixer/blob/master/setup.cfg"
    click CondaMeta "https://github.com/openmm/pdbfixer/blob/master/devtools/conda-recipe/meta.yaml"
    click CondaBuild "https://github.com/openmm/pdbfixer/blob/master/devtools/conda-recipe/build.sh"
    click EnvSpec "https://github.com/openmm/pdbfixer/blob/master/devtools/environment-dev.yaml"
    click TravisConfig "https://github.com/openmm/pdbfixer/blob/master/.travis.yml"
    click TravisScripts "https://github.com/openmm/pdbfixer/tree/master/devtools/travis-ci/"
    click GHActions "https://github.com/openmm/pdbfixer/blob/master/.github/workflows/CI.yml"
    click DocsScript "https://github.com/openmm/pdbfixer/blob/master/devtools/travis-ci/push-docs-to-s3.py"
    click UnitTests "https://github.com/openmm/pdbfixer/tree/master/pdbfixer/tests/"
    click Manual "https://github.com/openmm/pdbfixer/blob/master/Manual.html"
    click Readme "https://github.com/openmm/pdbfixer/blob/master/README.md"

    %% Styles
    classDef code fill:#a8f0a1,stroke:#333
    classDef data fill:#90caf9,stroke:#333
    classDef ui fill:#ffcc80,stroke:#333
    classDef external fill:#eeeeee,stroke:#333,stroke-dasharray:5 5
```
