# bluewallet/bluewallet architecture

> Architecture diagram of the GitHub repository bluewallet/bluewallet, 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/bluewallet/bluewallet
- Repository: https://github.com/bluewallet/bluewallet

## Overview

##### Project Overview & Type
- BlueWallet is a mobile Bitcoin and Lightning Network wallet built with React Native and Electrum as its backend for blockchain connectivity. The project is built for iOS and Android, and it uses native modules alongside JavaScript/TypeScript code.
- The app is entirely client-side, handling key management, wallet operations, encryption, and network interactions (e.g., connecting to Electrum servers for blockchain data and interacting with Lightning nodes).

##### Main Components
A. User Interface Layer (Mobile Frontend)
- React Native Screens, Components, and Navigation
– Folders: “screen”, “components”, “navigation”
- UI styling and context providers are implemented via hooks, contexts (see “hooks/context”) and theming defined in “components/themes.ts”.

B. Business Logic / Core Wallet Modules
- Wallet functionalities and crypto operations are encapsulated in directories “class” and “blue_modules”.
– “class” includes wallet types (legacy, segwit, lightning, multisig, etc.), encryption, key management, and transaction-building logic.
– “blue_modules” includes modules handling Electrum client connections, blockchain encoding/decoding (e.g., bc-bech32, bc-ur), handling clipboard interactions, and other utilities.
- “helpers” and “utils” which provide functions to support wallet operations and API integration.

C. Data Persistence & State Management
- Local device storage is used for securely storing keys, wallet settings, and user data.
– Look at files like “class/synced-async-storage.ts” and the usage of context providers for settings and storage.
- This layer might also interact with native secure storage modules provided in the “react-native-bw-file-access” package under “blue_modules”.

D. Native Integration Layer
- Platform-specific native components are maintained separately:
– “ios” and “android” directories contain native code and configuration projects.
– They implement integrations such as keychain access (iOS), native UI components, widgets, and handling platform-specific permissions.
– For example, the “ios” folder includes Xcode projects and Objective-C/Swift code, and the “android” folder contains Kotlin/Java code plus configuration like “build.gradle”.

E. External & API Integration Layer
- Electrum network client for connecting to Bitcoin network nodes.
– This is implemented via “blue_modules/BlueElectrum.ts” and other modules integrating with Electrum servers.
- Lightning network support is also integrated with dedicated screens and modules (see “screen/lnd”).
- Other external services include market data APIs and blockchain explorers (referenced in files like “MarketAPI”, “MarketData” located under Android native modules and iOS shared code).

F. CI, Testing, and Build Tools
- While not part of runtime architecture, include a note on the integration of CI/CD.
– Directories and files (.github/workflows, CircleCI configs, fastlane scripts) support automated builds/tests for iOS and Android.
- Unit and integration tests (under “tests”) help ensure that wallet components and integrations behave as expected.

##### Relationships and Data Flow
- Start from the user interacting with the UI layer.
- UI components communicate with business logic components through context providers and hooks.
- Business logic modules handle wallet operations (e.g., creating transactions, managing keys) and then call out to the network integration layer to fetch blockchain data or broadcast transactions.
- Network calls are made via Electrum and Lightning APIs, which then return data that updates the UI.
- Data persistence and secure storage ensure that sensitive data remains only on the device.
- Native integration components allow deeper platform-specific functionality, such as widgets and background processing.

##### Architectural & Design Patterns Highlighted
- Separation of concerns: UI (presentation), business logic (models/services), and native/infrastructure layers.
- Component-based architecture using React Native’s modularity (clear separation in “components”, “navigation”).
- Strong emphasis on modularity and extensibility (as seen in “blue_modules” and “class” which isolate wallet implementations and crypto operations).
- Use of context and hooks to manage application state and interactions.
- Testing is an integral element, evidencing robust automated testing strategies (unit, integration, end-to-end).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Node
    User["Mobile User"]:::external

    %% User Interface Layer
    subgraph "User Interface Layer"
        UI_Screens["Screens (React Native)"]:::ui
        UI_Components["UI Components"]:::ui
        UI_Navigation["Navigation"]:::ui
        UI_Theme["Theme Providers"]:::ui
        UI_Context["Context Providers"]:::ui
        UI_Hooks["Hooks"]:::ui
    end

    %% Business Logic / Core Wallet Modules
    subgraph "Business Logic / Core Wallet Modules"
        BL_Wallet["Wallet & Crypto Modules"]:::business
        BL_Utility["Utility Modules"]:::business
    end

    %% Data Persistence & State Management
    subgraph "Data Persistence & State Management"
        DP_Storage["Local Storage"]:::data
    end

    %% Native Integration Layer
    subgraph "Native Integration Layer"
        NI_iOS["iOS Modules"]:::native
        NI_Android["Android Modules"]:::native
    end

    %% External & API Integration Layer
    subgraph "External & API Integration Layer"
        EA_Electrum["Electrum Client"]:::external
        EA_Lightning["Lightning Network"]:::external
        EA_Market_Android["Market Data (Android)"]:::external
        EA_Market_iOS["Market Data (iOS)"]:::external
    end

    %% CI, Testing & Build Tools
    subgraph "CI, Testing & Build Tools"
        CI_CD["CI/CD Workflows"]:::ci
        CI_Fastlane["Fastlane Scripts"]:::ci
        CI_Tests["Test Suites"]:::ci
    end

    %% Flow Connections
    User -->|"uses"| UI_Screens
    User --> UI_Components
    User --> UI_Navigation
    User --> UI_Theme
    User --> UI_Context
    User --> UI_Hooks

    %% UI to Business Logic
    UI_Screens -->|"triggers"| BL_Wallet
    UI_Components --> BL_Wallet
    UI_Navigation --> BL_Wallet
    UI_Theme --> BL_Wallet
    UI_Context --> BL_Wallet
    UI_Hooks --> BL_Wallet

    %% Business Logic interactions
    BL_Wallet -->|"stores data in"| DP_Storage
    BL_Wallet -->|"invokes native"| NI_iOS
    BL_Wallet --> NI_Android

    BL_Utility -->|"calls"| EA_Electrum
    BL_Utility --> EA_Lightning
    BL_Utility -->|"fetches"| EA_Market_Android
    BL_Utility --> EA_Market_iOS

    %% External API responses back to Business Logic
    EA_Electrum -->|"returns data"| BL_Wallet
    EA_Lightning --> BL_Wallet
    EA_Market_Android --> BL_Wallet
    EA_Market_iOS --> BL_Wallet

    %% Business Logic updates UI
    BL_Wallet -->|"updates"| UI_Screens

    %% CI/CD integration (dashed relationships)
    CI_CD ---|"automates"| BL_Wallet
    CI_Fastlane --- BL_Wallet
    CI_Tests --- BL_Wallet

    %% Class Definitions for Styling
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef business fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef data fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef native fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef ci fill:#D8BFD8,stroke:#000,stroke-width:2px;

    %% Click Events for User Interface Layer
    click UI_Screens "https://github.com/bluewallet/bluewallet/tree/master/screen"
    click UI_Components "https://github.com/bluewallet/bluewallet/tree/master/components"
    click UI_Navigation "https://github.com/bluewallet/bluewallet/tree/master/navigation"
    click UI_Theme "https://github.com/bluewallet/bluewallet/blob/master/components/themes.ts"
    click UI_Context "https://github.com/bluewallet/bluewallet/tree/master/components/Context"
    click UI_Hooks "https://github.com/bluewallet/bluewallet/tree/master/hooks/context"

    %% Click Events for Business Logic / Core Wallet Modules
    click BL_Wallet "https://github.com/bluewallet/bluewallet/tree/master/class"
    click BL_Utility "https://github.com/bluewallet/bluewallet/tree/master/blue_modules"

    %% Click Event for Data Persistence
    click DP_Storage "https://github.com/bluewallet/bluewallet/blob/master/class/synced-async-storage.ts"

    %% Click Events for Native Integration Layer
    click NI_iOS "https://github.com/bluewallet/bluewallet/tree/master/ios"
    click NI_Android "https://github.com/bluewallet/bluewallet/tree/master/android"

    %% Click Events for External & API Integration Layer
    click EA_Electrum "https://github.com/bluewallet/bluewallet/blob/master/blue_modules/BlueElectrum.ts"
    click EA_Lightning "https://github.com/bluewallet/bluewallet/tree/master/screen/lnd"
    click EA_Market_Android "https://github.com/bluewallet/bluewallet/blob/master/android/app/src/main/java/io/bluewallet/bluewallet/MarketAPI.kt"
    click EA_Market_iOS "https://github.com/bluewallet/bluewallet/blob/master/ios/Shared/MarketAPI.swift"
    click EA_Market_iOS "https://github.com/bluewallet/bluewallet/blob/master/ios/Shared/MarketData.swift"

    %% Click Events for CI, Testing & Build Tools
    click CI_CD "https://github.com/bluewallet/bluewallet/tree/master/.github/workflows"
    click CI_Fastlane "https://github.com/bluewallet/bluewallet/tree/master/fastlane"
    click CI_Tests "https://github.com/bluewallet/bluewallet/tree/master/tests"
```
