# biocypher/graphpack architecture

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

- Interactive diagram: https://gitdiagram.com/biocypher/graphpack
- Repository: https://github.com/biocypher/graphpack

## Overview

##### Project Type and Purpose
- GraphPack is a Python library and CLI tool for compressing and visualizing large‐scale graphs (e.g., PPI networks).
- It exposes both a command‐line interface and a programmatic API, implements multiple compression algorithms, produces mapping files for lossless compression, and renders interactive visualizations.

##### Key Architectural Components
a. Entry Points
- CLI script (installed via setuptools entry_point)
- Python API (importable `graphpack` package)
b. Core Modules
- src/graphpack/compression.py   ← implements compression algorithms
- src/graphpack/utils.py         ← I/O, graph loading/saving, mapping file generation
c. Configuration & Assets
- src/graphpack/config           ← JSON/JS files holding physics and style options for visualization
d. Demo & Examples
- src/graphpack/demo/demo.py & sankey.py ← example workflows combining compression & visualization
e. Documentation
f. Tests
- tests/…                        ← unit tests for compression and utils
g. Data
- data/input/*.txt               ← sample graph inputs for demos/tests

##### External Dependencies
- Network manipulation: NetworkX (or igraph)
- Numerical & ML: NumPy, SciPy
- Visualization: D3.js (embedded via config JS), Matplotlib or Bokeh for static plots
- CLI: Click or argparse
- Documentation: Sphinx

##### Relationships and Data Flows
- CLI/API  → invokes compression module
- Compression module ↔ utils (for graph I/O & mapping file production)
- Compression output → passed to visualization sub‐module along with config assets
- Visualization sub‐module → emits HTML/JSON/SVG outputs
- Demo scripts → orchestrate CLI/API calls to produce end‐to‐end examples
- Tests → call core modules to validate algorithm correctness

##### Architectural Patterns & Design Principles
- Layered architecture:
1. Presentation (CLI/UI)
2. Application (API entry‐points, demos)
3. Domain/Business logic (compression algorithms)
4. Infrastructure (utilities, I/O, config files)
- Modular plugin‐style for adding new algorithms—each algorithm implemented as a function/class in `compression.py`.
- Separation of concerns: compression vs. visualization vs. I/O vs. configuration.

##### Final Advice
- Major directories (src, docs, tests, data) as contextual side‐bars.
- Pluggable algorithm interface in the compression module.
- How config assets drive the visualization options.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer (light blue)
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI Entry Point"]:::presentation
        API["Python API"]:::presentation
    end

    %% Application Layer (green)
    subgraph "Application Layer"
        direction TB
        Demo["Demo Scripts"]:::application
        Demo_End2End["End-to-end demo"]:::application
        Demo_Sankey["Sankey example"]:::application
    end

    %% Domain Logic (yellow)
    subgraph "Domain/Business Logic"
        direction TB
        Compression["Core Compression Module"]:::domain
        AlgorithmHook["Add New Algorithm Hook"]:::domain
    end

    %% Infrastructure Layer (gray)
    subgraph "Infrastructure Layer"
        direction TB
        Utils["Utilities / I-O Layer"]:::infrastructure
        Config["Configuration Assets"]:::infrastructure
        subgraph "Config Details"
            direction TB
            JS["JavaScript assets"]:::infrastructure
            JS_Old["Legacy JS assets"]:::infrastructure
            PhysBig["Physics options (big)"]:::infrastructure
            PhysSmall["Physics options (small)"]:::infrastructure
            ConstOpt["Constant options"]:::infrastructure
            StyleOpt["Style options"]:::infrastructure
        end
    end

    %% Visualization Module
    Visualization["Visualization Module"]:::domain

    %% File System / Outputs
    subgraph "Outputs & Data"
        direction TB
        FileSys["File System I/O"]:::infrastructure
        MappingFiles["Mapping Files"]:::infrastructure
        HTML["HTML/JSON/SVG Outputs"]:::infrastructure
        Logs["Logs"]:::infrastructure
        DataInput["Sample Data Input"]:::infrastructure
    end

    %% Documentation & Tests Sidebars
    subgraph "Supporting Artifacts"
        direction TB
        Docs["Documentation (Sphinx source)"]:::external
        Tests["Tests"]:::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        NX["NetworkX/igraph"]:::external
        NP["NumPy/SciPy"]:::external
        D3["D3.js"]:::external
        PlotLib["Matplotlib/Bokeh"]:::external
        CLI_Dep["Click/argparse"]:::external
        Sphinx["Sphinx"]:::external
    end

    %% Relationships
    CLI -->|"invokes"| Compression
    API -->|"calls"| Compression
    Compression -->|"uses I/O & mapping"| Utils
    Compression -->|"config JSON"| Config
    Utils -->|"reads/writes"| FileSys
    Compression -->|"graph object"| Visualization
    Config -->|"options"| Visualization
    Visualization -->|"outputs"| HTML
    Visualization -->|"logs"| Logs
    Demo --> Demo_End2End
    Demo --> Demo_Sankey
    Demo_End2End --> CLI
    Demo_End2End --> API
    Demo_Sankey --> Visualization
    Tests --> Compression
    Tests --> Utils
    Docs -->|"documents"| Compression
    Docs -->|"guides"| Visualization
    DataInput --> Utils

    %% Click Events
    click CLI "https://github.com/biocypher/graphpack/blob/main/pyproject.toml"
    click API "https://github.com/biocypher/graphpack/blob/main/src/graphpack/__init__.py"
    click Compression "https://github.com/biocypher/graphpack/blob/main/src/graphpack/compression.py"
    click Utils "https://github.com/biocypher/graphpack/blob/main/src/graphpack/utils.py"
    click Config "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/"
    click JS "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/additional_js/"
    click JS_Old "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/additional_js_old/"
    click PhysBig "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/physics_options_big/"
    click PhysSmall "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/physics_options_small/"
    click ConstOpt "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/const_options/"
    click StyleOpt "https://github.com/biocypher/graphpack/tree/main/src/graphpack/config/style_options/"
    click Demo_End2End "https://github.com/biocypher/graphpack/blob/main/src/graphpack/demo/demo.py"
    click Demo_Sankey "https://github.com/biocypher/graphpack/blob/main/src/graphpack/demo/sankey.py"
    click Docs "https://github.com/biocypher/graphpack/tree/main/docs/source/"
    click Tests "https://github.com/biocypher/graphpack/blob/main/tests/test_compression.py"
    click Tests "https://github.com/biocypher/graphpack/blob/main/tests/test_utils.py"
    click DataInput "https://github.com/biocypher/graphpack/blob/main/data/input/simple_graph.txt"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef application fill:#90EE90,stroke:#333,stroke-width:1px
    classDef domain fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
