# bytedance/protenix architecture

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

- Interactive diagram: https://gitdiagram.com/bytedance/protenix
- Repository: https://github.com/bytedance/protenix

## Overview

##### Project Purpose and Type
- Protenix is a trainable protein structure prediction tool (an AlphaFold3 reproduction) built in PyTorch.
- It supports both model training and inference, features a command-line interface (CLI), Docker deployment, and a web service (for online inference).
- Additional functionalities include MSA (Multiple Sequence Alignment) search, PDB/CIF conversion, and integration with external tools (e.g., Protenix-Dock for docking).

##### Main Components
A. Interface and Entry Points:
- CLI/Runner: Represented by the “runner” and “scripts” directories. This includes different command-line tools such as training (runner/train.py), inference (runner/inference.py), MSA search (runner/msa_search.py), and conversion utilities.
- Web Service: Represented by the “protenix/web_service” module. Capture that this component exposes endpoints (e.g., REST APIs) and integrates with the visualization tools (e.g., PyMOL integration).
- Notebooks: There’s a “notebooks” directory that provides example Jupyter notebooks (e.g., “protenix_inference.ipynb”) for interactive experimentation.

B. Core Processing Modules:
- Data Pipeline: Encompass the “protenix/data” module and related scripts. This component is responsible for data ingestion, preprocessing, JSON conversion from PDB/CIF files, MSA parsing (using “msa_featurizer.py” and “msa_utils.py”) and the pipeline to prepare training/inference input.
- Configuration: Both the “configs” directory and “protenix/config” package handle configurations (different settings for inference, training, and data pipelines).
- Model: Central to the project. The “protenix/model” module includes:
- Core network architecture (e.g., transformers, diffusion modules, embedders, pairformer).
- Loss functions and utility functions for predictions.
- The “layer_norm” submodule that shows custom CUDA kernels and integration of high-performance computing components.
- Extended Model Components: The “protenix/openfold_local” subdirectory integrates modules borrowed from OpenFold. These include additional data transformations, the dropout layer, triangular attention modules, and utilities for working with residue constants.

C. Supporting Components:
- Metrics and Evaluation: The “protenix/metrics” directory provides modules for computing metrics such as RMSD, LDDT, and clash calculations to evaluate model predictions.
- Utility Functions: “protenix/utils” (and nested subdirectories like permutation, torch_utils, etc.) encapsulate distributed training helpers, logging, file I/O, learning rate scheduling, and other support routines.
- Tests: A dedicated “tests” directory ensures the individual modules are verifiable via automated tests.
- Documentation and Examples: The “docs” and “examples” directories provide operational guides, MSA pipeline details, training setup, and inference examples.

##### Depicting Relationships and Data Flow
- That the “data” pipeline feeds into the “model” sub-system, where inputs are transformed into feature representations for training or inference.
- Once the model produces predictions, the results flow to:
- The output handling components (e.g., JSON converters, prediction visualization in the “web_service”).
- Evaluation modules (calculate metrics using code from “protenix/metrics”).
- Some dependency edges to external systems (e.g., Docker for deployment, PyTorch as the underlying compute framework, and optional integration with PyMOL or external MSA servers).

##### Architectural Patterns and Principles
- Modular separation by grouping components into distinct layers (Interface, Data Processing, Model, and Utilities).
- Clearly defined APIs between modules: the runners/scripts act as controllers that orchestrate calls to the data, model, and inference modules.
- That many modules (data parsing, configuration, and model utilities) adhere to separation-of-concerns, making it easier to extend or debug subsets of functionality.

##### Final Recommendations
- That each component has clear labels and that data flows (especially between the data pipeline, the model, and output reporting components) are explicit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        A1["Runner (CLI)\n(runner)"]:::interface
        A2["Scripts (CLI Tools)\n(scripts)"]:::interface
        A3["Notebooks (Jupyter)\n(notebooks/protenix_inference.ipynb)"]:::interface
        A4["Web Service\n(protenix/web_service)"]:::interface
    end

    %% Processing Layer
    subgraph "Processing Layer"
        B1["Data Pipeline\n(protenix/data)"]:::processing
        B2["Model\n(protenix/model)"]:::processing
        B3["Extended Model\n(protenix/openfold_local)"]:::processing
    end

    %% Utility & Support Layer
    subgraph "Utility & Support"
        C1["Configuration\n(configs)"]:::support
        C2["Metrics & Evaluation\n(protenix/metrics)"]:::support
        C3["Utility Functions\n(protenix/utils)"]:::support
        C4["Tests\n(tests)"]:::support
        C5["Documentation\n(docs)"]:::support
        C6["Examples\n(examples)"]:::support
    end

    %% External Dependencies
    D1["Docker"]:::external
    D2["PyTorch"]:::external
    D3["PyMOL"]:::external
    D4["External_MSA"]:::external

    %% Connections from User Interaction to Processing
    A1 -->|"uses"| B1
    A2 -->|"uses"| B1
    A3 -->|"triggers"| B1
    A4 -->|"calls"| B1

    %% Processing Layer internal flow
    B1 -->|"prepares_input"| B2
    B2 -->|"outputs_to"| A4
    A1 -->|"triggers_training"| B2

    %% Extended Model integrates with Model
    B3 -->|"enhances"| B2

    %% Model results flow to Metrics
    B2 -->|"evaluation"| C2

    %% Configuration influences Processing
    C1 -->|"configures"| B1
    C1 -->|"configures"| B2

    %% Utility Functions support Processing modules
    C3 -->|"supports"| B1
    C3 -->|"supports"| B2

    %% Tests validate Processing modules
    C4 -->|"validates"| B1
    C4 -->|"validates"| B2

    %% External dependencies integration
    D1 -->|"deploys"| A4
    D2 -->|"backbones"| B2
    D3 -->|"integrates"| A4
    D4 -->|"assists_MSA"| B1

    %% Styles
    classDef interface fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/bytedance/protenix/tree/main/runner"
    click A2 "https://github.com/bytedance/protenix/tree/main/scripts"
    click A3 "https://github.com/bytedance/protenix/blob/main/notebooks/protenix_inference.ipynb"
    click A4 "https://github.com/bytedance/protenix/tree/main/protenix/web_service"
    click B1 "https://github.com/bytedance/protenix/tree/main/protenix/data"
    click C1 "https://github.com/bytedance/protenix/tree/main/configs"
    click B2 "https://github.com/bytedance/protenix/tree/main/protenix/model"
    click B3 "https://github.com/bytedance/protenix/tree/main/protenix/openfold_local"
    click C2 "https://github.com/bytedance/protenix/tree/main/protenix/metrics"
    click C3 "https://github.com/bytedance/protenix/tree/main/protenix/utils"
    click C4 "https://github.com/bytedance/protenix/tree/main/tests"
    click C5 "https://github.com/bytedance/protenix/tree/main/docs"
    click C6 "https://github.com/bytedance/protenix/tree/main/examples"
```
