# ibm/differential-privacy-library architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/differential-privacy-library
- Repository: https://github.com/ibm/differential-privacy-library

## Overview

##### Main components
- Core Library Package (diffprivlib/)
- Mechanisms subpackage
- Models subpackage
- Tools subpackage
- Accountant module
- Transforms module
- Utils & validation modules
- External Dependencies
- NumPy, SciPy, scikit-learn, Matplotlib (used in examples)
- pytest (testing)
- Sphinx (documentation)
- setuptools (build & packaging)
- Supporting Artifacts
- Notebooks (Jupyter examples)
- Docs (Sphinx source & HTML output)
- Tests (pytest suite)
- CI/CD Workflows (GitHub Actions, CodeQL, codecov)
- Packaging & distribution (setup.py, PyPI)

##### Relationships & data flows
- Mechanisms are the foundational building blocks; Models and Tools import and invoke Mechanisms.
- Transforms sit alongside Mechanisms to preprocess or postprocess data within Mechanisms.
- Accountant tracks privacy budget across calls to Mechanisms within Models/Tools.
- Notebooks import Models, Tools, Mechanisms to demonstrate usage.
- Tests import all modules to validate correctness.
- CI/CD pipelines run tests, generate coverage, build docs, and push packaged releases.

##### Architectural patterns & design principles
- Layered architecture:
Layer 1 (Core DP primitives): diffprivlib.mechanisms, transforms, utils
Layer 2 (Higher‐level abstractions): diffprivlib.models, diffprivlib.tools, diffprivlib.accountant
Layer 3 (Interfaces & examples): notebooks, CLI (via setup.py entry points, if any)
- Modular, extensible design: clear separation between “Mechanisms” and “Models” so new DP algorithms can plug in.
- Test‐driven development: nearly every module has a corresponding pytest file.
- Continuous integration and documentation generation ensure code quality and user guidance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Container
    subgraph "diffprivlib (core library)"
        direction TB
        Core["diffprivlib/"]:::core
        subgraph "Core DP Primitives"
            direction TB
            Mech["Mechanisms"]:::core
            Trans["Transforms"]:::core
            Utils["Utils"]:::core
            Val["Validation"]:::core
        end
        subgraph "Higher-level Abstractions"
            direction TB
            Models["Models"]:::core
            Tools["Tools"]:::core
            Acc["Accountant"]:::core
        end
    end

    %% Relationships within Core
    Models -->|"imports"| Mech
    Tools -->|"imports"| Mech
    Models -->|"reports"| Acc
    Tools -->|"reports"| Acc
    Mech -->|"uses"| Trans
    Mech -->|"uses"| Utils
    Mech -->|"uses"| Val

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Numpy(("NumPy")):::external
        SciPy(("SciPy")):::external
        SKL(("scikit-learn")):::external
        MPL(("Matplotlib")):::external
        Pytest(("pytest")):::external
        Sphinx(("Sphinx")):::external
        Setuptools(("setuptools")):::external
    end

    %% Core to External
    Core -->|"requires"| Numpy
    Core -->|"requires"| SciPy
    Core -->|"requires"| SKL
    Core -->|"requires"| MPL
    Core -->|"requires"| Pytest
    Core -->|"requires"| Sphinx
    Core -->|"requires"| Setuptools

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        direction TB
        NB["Examples & Notebooks"]:::infra
        Tests["Tests (pytest suite)"]:::infra
        CI["CI/CD Workflows"]:::infra
        Docs["Documentation (Sphinx)"]:::infra
        Pack["Packaging & Distribution"]:::infra
    end

    %% Infrastructure Relationships
    NB -->|"demonstrates"| Core
    Tests -->|"validates"| Core
    CI -->|"runs"| Tests
    CI -->|"builds"| Docs
    CI -->|"publishes"| Pack

    %% Packaging & Distribution details
    subgraph "Package Files"
        direction TB
        SP["setup.py"]:::infra
        SC["setup.cfg"]:::infra
        RD["readthedocs.yml"]:::infra
    end
    Pack --> SP
    Pack --> SC
    Pack --> RD

    %% Click Events
    click Core "https://github.com/ibm/differential-privacy-library/tree/main/diffprivlib/"
    click Mech "https://github.com/ibm/differential-privacy-library/tree/main/diffprivlib/mechanisms/"
    click Trans "https://github.com/ibm/differential-privacy-library/tree/main/diffprivlib/mechanisms/transforms/"
    click Utils "https://github.com/ibm/differential-privacy-library/blob/main/diffprivlib/utils.py"
    click Val "https://github.com/ibm/differential-privacy-library/blob/main/diffprivlib/validation.py"
    click Models "https://github.com/ibm/differential-privacy-library/tree/main/diffprivlib/models/"
    click Tools "https://github.com/ibm/differential-privacy-library/tree/main/diffprivlib/tools/"
    click Acc "https://github.com/ibm/differential-privacy-library/blob/main/diffprivlib/accountant.py"
    click NB "https://github.com/ibm/differential-privacy-library/tree/main/notebooks/"
    click Docs "https://github.com/ibm/differential-privacy-library/tree/main/docs/"
    click Tests "https://github.com/ibm/differential-privacy-library/tree/main/tests/"
    click CI "https://github.com/ibm/differential-privacy-library/tree/main/.github/workflows/"
    click SP "https://github.com/ibm/differential-privacy-library/blob/main/setup.py"
    click SC "https://github.com/ibm/differential-privacy-library/blob/main/setup.cfg"
    click RD "https://github.com/ibm/differential-privacy-library/blob/main/readthedocs.yml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
