# sparrowwallet/sparrow architecture

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

- Interactive diagram: https://gitdiagram.com/sparrowwallet/sparrow
- Repository: https://github.com/sparrowwallet/sparrow

## Overview

##### Main components
- User Interface (UI) Layer:
– Built with JavaFX.
– FXML and CSS files in the resources (e.g., app.fxml, dialog.css, various FXML files in “com/sparrowwallet/sparrow/…”).
– Terminal and window/dialog components (e.g., controllers in terminal/wallet, AboutController, WelcomeController, etc.).
- Core Business Logic & Wallet Management:
– Packages like “com/sparrowwallet/sparrow/wallet”, “com/sparrowwallet/sparrow/transaction”, “com/sparrowwallet/sparrow/io”, and “com/sparrowwallet/sparrow/instance”.
– Domain classes managing transactions, keystores, wallet configurations, and handling the wallet’s life cycle.
- Networking & Blockchain Interaction:
– Network packages (“com/sparrowwallet/sparrow/net” and its subpackages including Electrum, Tor, and bitcoind integrations).
– Classes managing connectivity, fee rates, and event handling for blockchain (e.g., new block notifications).
- Hardware Wallet & External Device Integrations:
– Lots of “io” subpackages such as “ckcard”, “satochip”, “paynym” and others that encapsulate protocols for interfacing with hardware wallets.
– These components expose APIs that send commands to or receive data from external hardware devices.
- Persistence & Database:
– “io/db” package with DAO classes and mappers for wallet and transaction persistence.
– SQL scripts in “resources/com/sparrowwallet/sparrow/sql” marking the evolution of the database.
- Build and Deployment Infrastructure:
– Gradle build scripts, custom build tasks under “buildSrc” (especially for JavaFX handling), and deployment configurations found in “src/main/deploy” – which are responsible for packaging binaries for Linux, OS X, and Windows.
– Also, native libraries placed in “src/main/resources/native” are used to interact with platform-specific functions (such as JNI for Bitcoin Core connectivity, ZBar, etc.).
- Event Management & Services:
– An extensive events package (“com/sparrowwallet/sparrow/event”) that handles error/status/transaction notifications, ensuring decoupled communication between modules.

##### Relationships and interactions
- The UI Layer communicates with the Business Logic layer via controllers and event listeners.
- Business Logic interacts with Persistence (via DAOs) to store wallet details and transaction histories and with Networking services to request data from external Bitcoin nodes or Electrum servers.
- Dedicated modules handle hardware wallet communications and expose interfaces to the rest of the application.
- The build system, configured via Gradle scripts (with custom JavaFX plugins), integrates the overall project into native executables and installers and separates configurations for different networks (mainnet, testnet, etc.).
- The event system serves as the glue that decouples UI, network responses, and wallet updates, using directional events to signal state changes.

##### Architectural patterns and design principles
- Modular Design: Clearly separated packages for UI, core logic, networking, persistence, and hardware interfacing.
- MVC/MVVM Pattern: Controllers and FXML files suggest a typical JavaFX design pattern separating view logic from business logic.
- Event-Driven Architecture: Numerous event classes indicate observers and listeners are widely used for inter-module communication.
- Cross-Platform Deployment: Native resource directories and different deployment packages show that platform-specific concerns are abstracted away from core modules.

##### Technologies, frameworks, or libraries to note
- Java 22 (required runtime version) and JavaFX for the GUI.
- Gradle (with custom build scripts under “buildSrc”) for build automation and packaging (using jpackage, WiX for Windows installers, etc.).
- JDBC or similar persistence frameworks for database interactions, given the presence of SQL scripts and DAOs.
- External integrations such as Tor, Electrum servers, and hardware wallet API implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Tier
    subgraph "Presentation Tier"
        UI_FX["JavaFX UI (FXML & CSS)"]:::ui
        UI_CTRL["UI Controllers"]:::ui
    end

    %% Business Logic Tier
    subgraph "Business Logic Tier"
        WALLET_TX["Wallet & Transaction Management"]:::logic
        SPARROW_MAIN["SparrowWallet Main"]:::logic
    end

    %% Data Access Tier
    subgraph "Data Access Tier"
        DAO["DAO & Persistence Layer"]:::data
        SQL["SQL Scripts"]:::data
    end

    %% External Integrations
    subgraph "External Integrations"
        NETWORK["Blockchain Network (Bitcoind, Electrum, Tor)"]:::network
        HARDWARE["Hardware Wallet API"]:::hardware
    end

    %% Build & Deployment Tier
    subgraph "Build & Deployment Tier"
        GRADLE["Gradle Build Scripts"]:::build
        DEPLOY["Deployment Configurations"]:::build
        NATIVE["Native Libraries"]:::build
    end

    %% Event Management
    EVENT["Event System"]:::event

    %% Connections (vertical orientation)
    UI_CTRL -->|"triggers"| WALLET_TX
    UI_CTRL -->|"registers"| EVENT
    WALLET_TX -->|"persists"| DAO
    WALLET_TX -->|"records"| SQL
    WALLET_TX -->|"invokes"| NETWORK
    NETWORK -->|"notifies"| EVENT
    WALLET_TX -->|"interacts"| HARDWARE
    SPARROW_MAIN -->|"orchestrates"| WALLET_TX
    GRADLE -->|"configures"| DEPLOY
    GRADLE -->|"includes"| NATIVE
    DEPLOY -->|"packages"| UI_FX
    DEPLOY -->|"packages"| SPARROW_MAIN
    EVENT ---|"updates"| UI_FX

    %% Click Events for Presentation Tier
    click UI_FX "https://github.com/sparrowwallet/sparrow/blob/master/src/main/resources/com/sparrowwallet/sparrow/app.fxml"
    click UI_FX "https://github.com/sparrowwallet/sparrow/blob/master/src/main/resources/com/sparrowwallet/sparrow/app.css"
    click UI_CTRL "https://github.com/sparrowwallet/sparrow/blob/master/src/main/java/com/sparrowwallet/sparrow/AboutController.java"
    click UI_CTRL "https://github.com/sparrowwallet/sparrow/blob/master/src/main/java/com/sparrowwallet/sparrow/WelcomeController.java"
    click UI_CTRL "https://github.com/sparrowwallet/sparrow/blob/master/src/main/java/com/sparrowwallet/sparrow/AppController.java"

    %% Click Events for Business Logic Tier
    click WALLET_TX "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/wallet"
    click WALLET_TX "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/transaction"
    click SPARROW_MAIN "https://github.com/sparrowwallet/sparrow/blob/master/src/main/java/com/sparrowwallet/sparrow/SparrowWallet.java"

    %% Click Events for External Integrations
    click NETWORK "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/net/cormorant/electrum"
    click NETWORK "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/net/cormorant/bitcoind"
    click HARDWARE "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/io/ckcard"
    click HARDWARE "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/io/satochip"

    %% Click Events for Data Access Tier
    click DAO "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/io/db"
    click SQL "https://github.com/sparrowwallet/sparrow/tree/master/src/main/resources/com/sparrowwallet/sparrow/sql"

    %% Click Events for Build & Deployment Tier
    click GRADLE "https://github.com/sparrowwallet/sparrow/blob/master/build.gradle"
    click GRADLE "https://github.com/sparrowwallet/sparrow/tree/master/buildSrc"
    click DEPLOY "https://github.com/sparrowwallet/sparrow/tree/master/src/main/deploy"
    click NATIVE "https://github.com/sparrowwallet/sparrow/tree/master/src/main/resources/native"

    %% Click Event for Event Management
    click EVENT "https://github.com/sparrowwallet/sparrow/tree/master/src/main/java/com/sparrowwallet/sparrow/event"

    %% Class Styles
    classDef ui fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef logic fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef data fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef network fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef hardware fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef event fill:#fefefe,stroke:#343a40,stroke-width:2px;
```
