# zama-ai/tfhe-rs architecture

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

- Interactive diagram: https://gitdiagram.com/zama-ai/tfhe-rs
- Repository: https://github.com/zama-ai/tfhe-rs

## Overview

##### Main Components
- API Layers:
– Rust High-Level API: This is the primary interface for developers working in Rust. It uses abstraction layers (prelude modules, clear type definitions such as FheUint8, FheUint32, etc.).
– C API: Exposes FFI bindings for clients in C.
– Client-side WASM API: Provides a JavaScript-friendly API via WebAssembly.
- Core Cryptographic Modules:
– Boolean, Integer, and Shortint modules: These encapsulate specific TFHE functionalities including homomorphic operations, key switching, bootstrapping, and ciphertext operations.
– Core core_crypto library: Implements low-level cryptographic algorithms, including programmable bootstrapping, key switching, noise handling, and modular arithmetic.
- Backend Implementations:
– CPU Backend: Typical execution through standard Rust code.
– GPU/CUDA Backend: Located under backends/tfhe-cuda-backend; handles operations accelerated on GPUs using CUDA.
– FFT/NTT Modules: (tfhe-fft and tfhe-ntt) provide efficient numerical transforms used in the cryptographic algorithms.
– ZK Proof Modules: (tfhe-zk-pok) cater to zero‑knowledge proof variants and additional verifiability.
- Supporting Infrastructure:
– Key Generation & Caching: Modules that generate client keys and server keys and manage key caches.
– Utilities and Tests: Extensive tests (unit, integration, benchmark scripts) and CI/CD configurations (GitHub workflows, clang-format scripts, etc.).
– Documentation/Resources: Included in docs, README, tutorials, and handbook assets.
– Build & Package Management: Cargo files, Makefile, and configuration files.

##### Relationships and Interactions
- Data Flow:
– The client application (or developer’s code) uses the high-level API (via Rust, C, or WASM) to perform operations such as encrypting input, applying homomorphic functions, and decrypting outputs.
– Internally, these API calls interact with the core cryptographic modules that rely heavily on algorithms in core_crypto, boolean, integer, and shortint directories.
– The backend modules (e.g., tfhe-cuda-backend, tfhe-fft, tfhe-ntt) are called by the core cryptographic functions to accelerate computations on appropriate hardware (CPU vs. GPU).
– Configuration flows (e.g., the ConfigBuilder used in user samples) govern key generation and parameter selection.
– Represent the FFI boundary between the Rust and C APIs, as well as the WASM interface to JavaScript.
– Illustrate the key generation and key distribution pipeline: a “Key Generation” module generating a client key and corresponding server keys, then a “Set Server Key” call for server-side computation.

##### Architectural Patterns and Technologies
- Modularity & Separation of Concerns:
– The library is split into well-defined modules (e.g., boolean, integer, shortint, core_crypto) which simplifies maintenance and allows targeted testing.
- Abstraction Layers:
– The high-level API abstracts the low-level details, creating clean boundaries between user-facing functions and underlying cryptographic algorithms.
- Multiple Hardware Targets:
– The separation between CPU and GPU backends underpins the design’s flexibility and scalability.
- External Dependencies:
– The project is a pure Rust implementation, with CI/CD configured via GitHub workflows and third-party benchmarking and testing tools.
– The availability of C and WASM APIs shows an intent to support a wide ecosystem.

– GPU/CUDA backend (tfhe-cuda-backend)
– FFT/NTT accelerators (tfhe-fft, tfhe-ntt)
– ZK and other optional modules (tfhe-zk-pok)
– From API components to core modules.
– From core modules to backend implementations.
– Illustrate the feedback loop of key generation (from configuration to client key generation then to setting server keys).
- Annotations:
– Indicate dependencies such as “built with Cargo”, “tested with CI scripts”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layers
    subgraph "API Layers"
        A1["Rust High-Level API"]:::api
        A2["C API (FFI Bindings)"]:::api
        A3["WASM API"]:::api
    end

    %% Core Cryptographic Modules
    subgraph "Core Cryptographic Modules"
        B1["Boolean Module"]:::core
        B2["Integer Module"]:::core
        B3["Shortint Module"]:::core
        B4["Core Crypto Module"]:::core
    end

    %% Backend Implementations
    subgraph "Backend Implementations"
        C1["GPU/CUDA Backend"]:::backend
        C2["FFT Accelerator"]:::backend
        C3["NTT Accelerator"]:::backend
        C4["ZK Proof Module"]:::backend
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        D1["Key Generation & Caching"]:::support
        D2["Utilities & Tests"]:::support
        D3["Documentation & Resources"]:::support
        D4["Cargo.toml"]:::support
        D5["Makefile"]:::support
    end

    %% Connections from API Layers to Core Cryptographic Modules
    A1 -->|"calls"| B1
    A1 -->|"calls"| B2
    A1 -->|"calls"| B3
    A1 -->|"calls"| B4
    A2 -->|"FFI"| B4
    A3 -->|"WASM"| B4

    %% Connections from Core Cryptographic Modules to Backend Implementations
    B4 -->|"accelerates"| C1
    B4 -->|"accelerates"| C2
    B4 -->|"accelerates"| C3
    B4 -->|"accelerates"| C4

    %% Key Generation and Distribution Flow
    D1 -->|"supplies_keys"| A1
    D1 -->|"supplies_keys"| B4

    %% Class Definitions with Colors
    classDef api fill:#a2d5f2,stroke:#000,stroke-width:2px;
    classDef core fill:#e4c1f9,stroke:#000,stroke-width:2px;
    classDef backend fill:#f6a5a5,stroke:#000,stroke-width:2px;
    classDef support fill:#c1e1c1,stroke:#000,stroke-width:2px;

    %% Click Events for API Layers
    click A1 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/high_level_api"
    click A2 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/c_api"
    click A3 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/js_on_wasm_api"

    %% Click Events for Core Cryptographic Modules
    click B1 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/boolean"
    click B2 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/integer"
    click B3 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/shortint"
    click B4 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/core_crypto"

    %% Click Events for Backend Implementations
    click C1 "https://github.com/zama-ai/tfhe-rs/tree/main/backends/tfhe-cuda-backend"
    click C2 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe-fft"
    click C3 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe-ntt"
    click C4 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe-zk-pok"

    %% Click Events for Supporting Infrastructure
    click D1 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/src/keycache"
    click D2 "https://github.com/zama-ai/tfhe-rs/tree/main/tests"
    click D3 "https://github.com/zama-ai/tfhe-rs/tree/main/tfhe/docs"
    click D4 "https://github.com/zama-ai/tfhe-rs/blob/main/Cargo.toml"
    click D5 "https://github.com/zama-ai/tfhe-rs/tree/main/Makefile"
```
