# blockstream/gdk architecture

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

- Interactive diagram: https://gitdiagram.com/blockstream/gdk
- Repository: https://github.com/blockstream/gdk

## Overview

Based on your project’s file structure and README, the Green C/C++ SDK is a cross-platform, cross-language library designed for Blockstream Green wallets. It uses a modular, multi-language approach (primarily C/C++ core with Rust subprojects, and wrappers for Java, Python, and Swift) and an advanced, multi-platform build and deployment system (using CMake, Docker, and extensive build scripts).

##### Main Components
- Core SDK (C/C++ Library):
- Represented by files in the “src” directory (e.g., core functionality like session management, signing, transaction utilities, caching, network handling, etc.).
- Language Bindings/ Wrappers:
- SWIG-based wrappers located in “src/swig_java” for Java and “src/swig_python” for Python.
- Swift wrapper under “src/swift/GreenGDK” for Swift integration.
- Rust Subcomponents:
- Multiple Rust subprojects under “subprojects/gdk_rust” such as:
▫ “gdk_rust/gdk_common”: Handles common backend functionality.
▫ “gdk_rust/gdk_electrum”: Provides Electrum-specific functionalities.
▫ “gdk_rust/gdk_pin_client” and “gdk_rust/gdk_registry”: Additional capabilities (e.g., PIN handling, asset registry).
- These components are a critical pillar supporting parts of the SDK’s core logic.
- Build System:
- CMake configuration files (root-level CMakeLists.txt, “src/CMakeLists.txt”, and extensive CMake profiles & modules under “cmake”).
- Build scripts in “tools” for compiling dependencies, building the SDK, and cleaning.
- Docker configurations in “docker” that help provide reproducible build environments across platforms.
- Testing and CI:
- Test cases under “tests” and CI config files like “.gitlab-ci.yml” for continuous integration.
- Documentation:
- Managed in “docs” and the README links to ReadTheDocs for API documentation.

##### Relationships and Data Flow
- The Core SDK (C/C++ implementation) is the central component.
- Language bindings (Java, Python, Swift) interact with the core library via SWIG-generated interfaces or direct wrapper calls.
- Rust subprojects provide additional low-level and performance-critical functionalities. They are integrated and accessed by the C/C++ layer.
- The build system (CMake and build scripts) ties everything together. It is responsible for compiling both the core and the various language bindings while leveraging platform-specific profiles (from “cmake/profiles”) to target multiple architectures (Android, iOS, Windows, etc.).
- Docker images encapsulate the build environment ensuring consistency, and are integrated with the CI system (GitLab CI configuration) for automated builds.
- Testing frameworks interact with both the core functionalities and the language bindings to verify integrity.

##### Architectural Patterns and Design Principles
- Modularity: The SDK is broken into core functionality, multiple bindings, and separate Rust components.
- Cross-platform and cross-language design: Different wrappers and build profiles enable support for many platforms.
- Separation of Concerns: Clear boundaries are present between the core library, its build/deployment systems, and the language-specific bindings.
- Extensibility: The use of SWIG and modular subprojects (especially in Rust) provides points where additional features can be integrated in the future.

##### Relevant Technologies, Frameworks, and Libraries
- C/C++ for the core implementation.
- CMake as the primary build system with numerous build profiles.
- Docker for containerized builds and dependency management.
- Rust for several submodules using Cargo for building.
- SWIG for generating Java and Python bindings.
- GitLab CI for continuous integration.
- Platform-specific tools (Android NDK, platform-specific dependencies, etc.) as defined in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build System"
        BS1["CMake Build Files"]:::build
        BS2["Build Scripts"]:::build
        BS3["Docker Configurations"]:::build
    end

    CORE["Core SDK (C/C++)"]:::core

    subgraph "Rust Modules"
        R1["gdk_common"]:::rust
        R2["gdk_electrum"]:::rust
        R3["gdk_pin_client"]:::rust
        R4["gdk_registry"]:::rust
        R5["Rust Core"]:::rust
    end

    subgraph "Language Wrappers"
        LW1["Java Wrapper (SWIG)"]:::wrapper
        LW2["Python Wrapper (SWIG)"]:::wrapper
        LW3["Swift Wrapper"]:::wrapper
    end

    TCI["Testing & CI"]:::ci
    DOC["Documentation"]:::docs

    %% Build System to Core and other components
    BS1 --> CORE
    BS2 --> CORE
    BS3 --> CORE

    BS1 --> R1
    BS1 --> R2
    BS1 --> R3
    BS1 --> R4
    BS1 --> R5

    BS1 --> LW1
    BS1 --> LW2
    BS1 --> LW3

    BS2 --> TCI

    %% Rust Modules integration with Core SDK
    R1 --> CORE
    R2 --> CORE
    R3 --> CORE
    R4 --> CORE
    R5 --> CORE

    %% Language Wrappers interfacing with Core SDK
    LW1 --> CORE
    LW2 --> CORE
    LW3 --> CORE

    %% Components test interaction
    CORE --> TCI
    LW1 --> TCI
    LW2 --> TCI
    LW3 --> TCI
    R1 --> TCI
    R2 --> TCI
    R3 --> TCI
    R4 --> TCI
    R5 --> TCI

    %% Testing publishes documentation
    TCI --> DOC

    %% Click Events
    click CORE "https://github.com/blockstream/gdk/tree/master/src/"
    click LW1 "https://github.com/blockstream/gdk/tree/master/src/swig_java/"
    click LW2 "https://github.com/blockstream/gdk/tree/master/src/swig_python/"
    click LW3 "https://github.com/blockstream/gdk/tree/master/src/swift/GreenGDK/"
    click R1 "https://github.com/blockstream/gdk/tree/master/subprojects/gdk_rust/gdk_common/"
    click R2 "https://github.com/blockstream/gdk/tree/master/subprojects/gdk_rust/gdk_electrum/"
    click R3 "https://github.com/blockstream/gdk/tree/master/subprojects/gdk_rust/gdk_pin_client/"
    click R4 "https://github.com/blockstream/gdk/tree/master/subprojects/gdk_rust/gdk_registry/"
    click R5 "https://github.com/blockstream/gdk/tree/master/subprojects/gdk_rust/gdk_rust/"
    click BS1 "https://github.com/blockstream/gdk/tree/master/cmake/"
    click BS2 "https://github.com/blockstream/gdk/tree/master/tools/"
    click BS3 "https://github.com/blockstream/gdk/tree/master/docker/"
    click TCI "https://github.com/blockstream/gdk/tree/master/tests/"
    click DOC "https://github.com/blockstream/gdk/tree/master/docs/"

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef rust fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef wrapper fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ci fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef docs fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
```
