# steineggerlab/foldcomp architecture

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

- Interactive diagram: https://gitdiagram.com/steineggerlab/foldcomp
- Repository: https://github.com/steineggerlab/foldcomp

## Overview

##### Main Components
- Input Handler / File I/O: Modules responsible for reading protein structures (PDB/CIF) and managing input directories, tar files, or file lists.
- Core Compression & Decompression Engine: The heart of the project that processes the structure data. This includes:
- C++ compression code (foldcomp.cxx, src/foldcomp.cpp, etc.)
- Algorithms to convert 3D coordinates into torsion angles and then encode them into a small binary file (FCZ file format).
- Decompression logic that reverses the process.
- Python API and CLI Frontend:
- Command-line interface (the foldcomp executable) that wraps the compression/decompression routines and exposes various commands.
- The Python binding (foldcomp.py) that allows the same functionalities via a Python package.
- External Libraries and Dependencies:
- gemmi library for handling molecular data formats and any structure-specific functions.
- microtar (and possibly other utilities) for handling archive files.
- Build and Deployment Infrastructure:
- CMake configuration files that specify how to compile the C++ components.
- GitHub workflows (.github/workflows) for continuous integration and testing.
- Setup scripts (setup.py, build.sh) and packaging configuration (pyproject.toml) to build and distribute the software.
- Test and Example Suites:
- The test directory contains various examples and test files that verify the functionality of the system across different input types.

##### Representing Relationships and Data Flow
- How the user provides data (as PDB/CIF files, directories, or archives) to the system through the CLI or Python API.
- Python layer as an adapter/wrapper sitting on top of the core engine – interfacing with users through high-level APIs and using the underlying C++ routines.
- External libraries (gemmi and microtar) should be depicted as auxiliary modules that the Core Engine depends on for specialized tasks (e.g., structure parsing and archive operations).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system cleanly separates the file I/O, core computational logic (compression/decompression), and user interface layers.
- Modularity: The design is modular (with distinct directories for core source code, libraries, tests, examples, and CI workflows), making it easier to extend and maintain.
- Multi-language Interoperability: The project demonstrates a hybrid approach combining C++ performance with Python usability.
- Threading Support: There is a threading option in the commands, so indicate that the engine can leverage parallelization for performance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        A["User/Client"]:::client
        B["Input Handler / File I/O"]:::io
        C["C++ Compression & Decompression Engine"]:::engine
        D["CLI & Python API Frontend"]:::api
        E["Compressed FCZ File"]:::output
        F["Decompressed PDB/CIF"]:::output
        G["Extracted Data (pLDDT/Sequences)"]:::output
    end

    %% External Dependencies
    subgraph "External Dependencies"
        GEM["gemmi Library"]:::library
        MT["microtar Library"]:::library
    end

    %% Build and Deployment Infrastructure
    subgraph "Build & Deployment Infrastructure"
        H["Build & Deployment Infrastructure"]:::build
    end

    %% Test and Example Suites
    subgraph "Test & Example Suites"
        I["Test and Example Suites"]:::test
    end

    %% Data Flow Connections
    A -->|"providesInput"| B
    B -->|"feedsData"| C
    D -->|"invokesEngine"| C
    C -->|"producesCompressed"| E
    C -->|"producesDecompressed"| F
    C <-->|"supportsExtraction"| G
    C -->|"callsGemmi"| GEM
    C -->|"callsMicrotar"| MT
    H -->|"buildsEngine"| C
    H -->|"buildsAPI"| D
    I -->|"testsInput"| B
    I -->|"testsEngine"| C

    %% Click Events for Component Mapping
    click B "https://github.com/steineggerlab/foldcomp/blob/master/src/input_processor.h"
    click C "https://github.com/steineggerlab/foldcomp/blob/master/foldcomp/foldcomp.cxx"
    click C "https://github.com/steineggerlab/foldcomp/blob/master/src/foldcomp.cpp"
    click D "https://github.com/steineggerlab/foldcomp/blob/master/foldcomp/foldcomp.py"
    click D "https://github.com/steineggerlab/foldcomp/blob/master/foldcomp/setup.py"
    click GEM "https://github.com/steineggerlab/foldcomp/tree/master/lib/gemmi"
    click MT "https://github.com/steineggerlab/foldcomp/tree/master/lib/microtar"
    click H "https://github.com/steineggerlab/foldcomp/blob/master/CMakeLists.txt"
    click H "https://github.com/steineggerlab/foldcomp/blob/master/src/CMakeLists.txt"
    click H "https://github.com/steineggerlab/foldcomp/blob/master/build.sh"
    click I "https://github.com/steineggerlab/foldcomp/tree/master/test/"
    click I "https://github.com/steineggerlab/foldcomp/blob/master/foldcomp-py-examples.ipynb"

    %% Styles
    classDef client fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef io fill:#ccf,stroke:#333,stroke-width:2px;
    classDef engine fill:#cfc,stroke:#333,stroke-width:2px;
    classDef api fill:#fdd,stroke:#333,stroke-width:2px;
    classDef output fill:#cff,stroke:#333,stroke-width:2px;
    classDef library fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef test fill:#98fb98,stroke:#333,stroke-width:2px;
```
