# etospheres-labs/etopay-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/etospheres-labs/etopay-sdk
- Repository: https://github.com/etospheres-labs/etopay-sdk

## Overview

##### Project Type and Purpose
- This is ETOPay SDK: a multi‐language, decentralized payment SDK written in Rust.
- It exposes core payment, wallet and transaction functionality via a central Rust “sdk” crate and several support crates (api_types, etopay-wallet), and then generates bindings for Android (JNI), iOS/Swift (FFI), and WebAssembly/JavaScript.

##### File‐Structure Analysis
- Top‐level Rust crates:
- api_types/ – definitions of all API types (networks, transactions, KYC, viviswap, etc.)
- crates/etopay-wallet/ – low‐level on‐chain wallet client, RPC wrappers, crypto primitives
- sdk/ – high‐level orchestration: configuration, core business logic, backend modules (DLT, KYC, transactions, postident, viviswap), user & wallet management, types, error handling, examples, and tests
- bindings/ – subfolders for android, swift, wasm, each containing build scripts, FFI glue (JNI, module maps, wasm-pack), and examples
- testing/ – end-to-end test harness connecting to Keycloak, cleanup, auth flows
- Supplementary: docs/ (MkDocs site), CI/CD pipelines under .github/workflows, Makefile, devcontainer, sonar, linters, etc.

##### Key Insights from README
- Core SDK crates published on crates.io
- Quickstart repos in four languages, demonstrating platform integration
- Comprehensive docs site for architecture, examples, modules

##### Diagramming the Architecture
1. API Types Crate (“api_types”)
2. Wallet Client Crate (“etopay-wallet”)
3. Core SDK Crate (“sdk”)
4. Language/Platform Bindings:
– Android (JNI layer, Java wrappers)
– Swift (FFI layer, Swift package)
– WebAssembly (wasm-pack, JS/TS wrappers)
5. Example Apps & Tests (Rust examples, Android tests, Swift examples, wasm examples)
6. External Services:
– Decentralized Ledger (DLT RPC endpoints)
– KYC/Postident services
– Viviswap exchange API

c. Architectural Patterns & Principles
- Modular micro-crate architecture: separation of concerns (types vs. wallet vs. orchestrator)
- Adapter/FFI pattern for multi-platform support (JNI for Android, module maps for Swift, wasm-pack for JS)
- Clear layering: Core logic → FFI bindings → Consumer apps
- Dependency inversion: core logic depends on traits, wiring occurs in backend modules

d. Technologies & Frameworks
- Rust + Cargo workspaces
- JNI (Android bindings, Gradle wrapper)
- Swift Package Manager + bridging headers
- wasm-pack + webpack + TypeScript examples
- CI/CD: GitHub Actions for Rust, Android, Swift, wasm, GitHub Pages for docs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Tier 3: Examples & Tests
    subgraph "Tier 3: Examples & Tests"
        REX["Rust Examples"]:::examples
        ATEX["Android Tests"]:::examples
        SWEX["Swift Examples"]:::examples
        WSMEX["WASM Examples"]:::examples
        E2E["E2E Test Harness"]:::examples
    end

    %% Tier 2: Platform Bindings
    subgraph "Tier 2: Platform Bindings"
        AND["Android Bindings"]:::bindings
        SWI["Swift Bindings"]:::bindings
        WASM["WASM/JS Bindings"]:::bindings
    end

    %% Tier 1: Core Crates
    subgraph "Tier 1: Core Crates"
        API["api_types"]:::core
        WLT["etopay-wallet"]:::core
        SDK["sdk"]:::core
    end

    %% External Services
    subgraph "External Services"
        DLT["DLT RPC Endpoint"]:::external
        KYC["KYC/Postident Service"]:::external
        VVS["Viviswap Exchange API"]:::external
    end

    %% Documentation
    DOC["Documentation Site"]:::docs

    %% Relationships
    SDK -->|"uses types"| API
    SDK -->|"delegates ledger calls"| WLT
    SDK -->|"calls HTTP RPC"| DLT
    SDK -->|"calls HTTP RPC"| KYC
    SDK -->|"calls HTTP RPC"| VVS
    SDK -->|"FFI boundary"| AND
    SDK -->|"FFI boundary"| SWI
    SDK -->|"wasm-pack"| WASM

    ATEX -->|"uses JNI"| AND
    SWEX -->|"uses FFI"| SWI
    WSMEX -->|"uses wasm bindings"| WASM
    REX -->|"direct examples"| SDK
    E2E -->|"tests flows"| SDK

    %% Click Events
    click API "https://github.com/etospheres-labs/etopay-sdk/tree/main/api_types/"
    click WLT "https://github.com/etospheres-labs/etopay-sdk/tree/main/crates/etopay-wallet/"
    click SDK "https://github.com/etospheres-labs/etopay-sdk/tree/main/sdk/"
    click AND "https://github.com/etospheres-labs/etopay-sdk/tree/main/bindings/android/"
    click SWI "https://github.com/etospheres-labs/etopay-sdk/tree/main/bindings/swift/"
    click WASM "https://github.com/etospheres-labs/etopay-sdk/tree/main/bindings/wasm/"
    click E2E "https://github.com/etospheres-labs/etopay-sdk/tree/main/testing/"
    click DOC "https://github.com/etospheres-labs/etopay-sdk/tree/main/docs/"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef bindings fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef external fill:#FAD7A0,stroke:#D68910,color:#7D6608
    classDef examples stroke-dasharray: 5 5,fill:#FFFFFF,stroke:#A6ACAF,color:#566573
    classDef docs fill:#E8DAEF,stroke:#7D3C98,color:#4A235A
```
