# breez/spark-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/breez/spark-sdk
- Repository: https://github.com/breez/spark-sdk

## Overview

##### Project type and purpose
- This is an open-source multi-language SDK (“Breez SDK – Nodeless (Spark Implementation)”) for self-custodial Bitcoin & Lightning integration using Spark (a Bitcoin-native Layer-2).
- It provides Rust core libraries, FFI bindings to Go, C#, Python, React Native, Swift, Flutter, WebAssembly, a CLI, and an LNURL microservice.

##### File structure
- Top-level workspace (Cargo.toml) with two main Rust workspaces:
- crates/breez-sdk – the SDK crates:
– bindings (uniffi-generated FFI layers)
– core & common (business logic, protocols, storage adapters)
– wasm (WebAssembly interface)
– cli (command-line client)
- crates/spark – the Spark protocol & operator client
- A microservice subdirectory: crates/breez-sdk/lnurl – a standalone HTTP service (Rust + Diesel/Postgres/SQLite migrations) exposing LNURL endpoints.
- packages/ – platform projects consuming the SDK: Flutter, React Native, Wasm examples
- docs/ – static site generator for HTML docs and code snippets per language
- .github/ – CI/CD workflows for building & publishing each binding
- regtest/ – scripts for integration tests against a local Bitcoin regtest

##### README for additional insights
- Clarifies SDK capabilities (payments, tokens, real-time sync, WebAssembly)
- Describes project layout (crates + packages)
- Lists features and supported languages
- Mentions the CLI and LNURL microservice

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Applications"
        direction TB
        Flutter["Flutter App"]:::external
        ReactNative["React Native App"]:::external
        WasmExample["WASM Example (Node)"]:::external
    end

    subgraph "Platform Bindings" 
        direction TB
        UniFFI["UniFFI Bindings"]:::sdkLayer
        Android["Android (Kotlin)"]:::sdkLayer
        CSharp["C# Binding"]:::sdkLayer
        Python["Python Binding"]:::sdkLayer
        Swift["Swift Binding"]:::sdkLayer
        KMP["Kotlin MPP Binding"]:::sdkLayer
        GoBinding["Go Binding Config"]:::sdkLayer
    end

    subgraph "SDK Core" 
        direction TB
        Common["Core: common (protocol models, gRPC & REST)"]:::sdkLayer
        CoreLogic["Core: logic (payment, token, sync)"]:::sdkLayer
        TokenConv["Token Conversion"]:::sdkLayer
        RealTimeSync["Real-time Sync Service"]:::network
        WASM["WebAssembly Module"]:::sdkLayer
        CLI["CLI Client"]:::sdkLayer
    end

    subgraph "LNURL Microservice" 
        direction TB
        LNURLAPI["LNURL HTTP API"]:::network
        LNURLRepo["Routes & Repo"]:::sdkLayer
        LNURLMigs["DB Migrations"]:::persistence
    end

    subgraph "Spark Protocol" 
        direction TB
        SparkCore["Spark Operator Client"]:::external
        SparkRPC["gRPC RPC Client"]:::network
        SparkServices["HTLC/Swap/Timelock"]:::external
        SparkProto["Protobuf Definitions"]:::sdkLayer
    end

    subgraph "Persistence & Docs"
        direction TB
        SQLite["SQLite Adapter"]:::persistence
        Postgres["Postgres Adapter"]:::persistence
        Docs["Documentation Site"]:::docs
        CI["CI/CD Workflows"]:::docs
        Regtest["Regtest Scripts"]:::docs
    end

    subgraph "External Networks"
        direction TB
        BitcoinNet["Bitcoin Network"]:::external
        LNURLExt["External LNURL Endpoints"]:::external
        Explorer["On-chain Explorer"]:::external
    end

    %% Connections
    Flutter -->|uses| UniFFI
    ReactNative -->|uses| UniFFI
    WasmExample -->|uses| WASM
    UniFFI -->|FFI calls| Common
    Android -->|FFI calls| Common
    CSharp -->|FFI calls| Common
    Python -->|FFI calls| Common
    Swift -->|FFI calls| Common
    KMP -->|FFI calls| Common
    GoBinding -->|FFI calls| Common

    Common -->|payment/token/sync| CoreLogic
    CoreLogic -->|token conv| TokenConv
    CoreLogic -->|persist| SQLite
    CoreLogic -->|persist| Postgres
    CoreLogic -->|grpc| RealTimeSync
    CoreLogic -->|rpc| SparkRPC
    CoreLogic -->|on-chain| BitcoinNet
    CLI -->|invokes| Common
    WASM -->|binds| Common

    RealTimeSync -->|grpc| Common
    SparkRPC -->|uses| SparkCore
    SparkCore -->|services| SparkServices
    SparkServices -->|proto| SparkProto

    LNURLAPI -->|calls| Common
    LNURLAPI -->|routes| LNURLRepo
    LNURLRepo -->|migrate| LNURLMigs
    LNURLAPI -->|db| Postgres

    Common -->|docs| Docs
    CI -->|build| UniFFI
    CI -->|test| CLI
    Regtest -->|tests| Common

    Common -->|explorer data| Explorer
    LNURLAPI -->|redirect| LNURLExt

    %% Click Events
    click Flutter "https://github.com/breez/spark-sdk/blob/main/packages/flutter/lib/breez_sdk_spark.dart"
    click ReactNative "https://github.com/breez/spark-sdk/blob/main/packages/react-native/src/NativeBreezSdkSparkReactNative.ts"
    click WasmExample "https://github.com/breez/spark-sdk/blob/main/packages/wasm/examples/node/src/cli.js"
    click UniFFI "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/src/lib.rs"
    click Android "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/langs/android/lib/src/main/AndroidManifest.xml"
    click CSharp "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/langs/csharp/src/Breez.Sdk.Spark.csproj"
    click Python "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/langs/python/setup.py"
    click Swift "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/langs/swift/Package.swift"
    click KMP "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/langs/kotlin-multiplatform/breez-sdk-spark-kmp-plugin/src/main/kotlin/technology/breez/spark/BreezSdkSparkPlugin.kt"
    click GoBinding "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/bindings/uniffi.toml"
    click Common "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/common/src/lib.rs"
    click CoreLogic "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/core/src/lib.rs"
    click TokenConv "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/core/src/token_conversion/mod.rs"
    click RealTimeSync "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/core/src/realtime_sync/mod.rs"
    click SQLite "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/core/src/persist/sqlite.rs"
    click Postgres "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/core/src/persist/postgres.rs"
    click CLI "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/cli/src/main.rs"
    click LNURLAPI "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/lnurl/src/main.rs"
    click LNURLRepo "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/lnurl/src/routes.rs"
    click LNURLMigs "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/lnurl/migrations/postgres/20250911_initial.sql"
    click WASM "https://github.com/breez/spark-sdk/blob/main/crates/breez-sdk/wasm/src/lib.rs"
    click SparkCore "https://github.com/breez/spark-sdk/blob/main/crates/spark/src/lib.rs"
    click SparkRPC "https://github.com/breez/spark-sdk/blob/main/crates/spark/src/operator/rpc/spark_rpc_client.rs"
    click SparkServices "https://github.com/breez/spark-sdk/blob/main/crates/spark/src/services/htlc.rs"
    click SparkProto "https://github.com/breez/spark-sdk/blob/main/crates/spark/protos/spark/spark.proto"
    click CI "https://github.com/breez/spark-sdk/blob/main/.github/workflows/ci.yaml"
    click Regtest "https://github.com/breez/spark-sdk/blob/main/regtest/request-funds.sh"

    %% Styles
    classDef sdkLayer fill:#AED6F1,stroke:#3498DB,color:#1B4F72
    classDef network fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef external fill:#F9E79F,stroke:#DC7633,color:#7D6608
    classDef persistence fill:#D5D8DC,stroke:#7B7D7D,color:#17202A
    classDef docs fill:#FADBD8,stroke:#C0392B,color:#641E16
```
