# spesmilo/electrum architecture

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

- Interactive diagram: https://gitdiagram.com/spesmilo/electrum
- Repository: https://github.com/spesmilo/electrum

## Overview

The Electrum project is a lightweight Bitcoin client written in Python with support for both a Qt and QML graphical user interface. Its purpose is to allow users to manage their Bitcoin wallet securely with support for advanced features such as hardware wallets and lightning network components. The project is structured to support multiple platforms (Linux, macOS, Windows, Android) and includes extensive testing, build scripts, and various plugin integrations.

##### Main Components
- Core Wallet & Business Logic: This is the heart of Electrum, located in the “electrum” directory. It includes modules for wallet management (wallet.py, wallet_db.py), transaction handling, blockchain interaction (blockchain.py), fee policies, and synchronization.
- GUI Layer: Two primary GUI implementations exist:
- Qt Interface: Found in “electrum/gui/qt” – typical desktop GUI components for dialogs, wallet management, QR scanning, etc.
- QML Interface: Found in “electrum/gui/qml” – for mobile and modern UI with QML components.
- Networking & Blockchain Interaction: Components like “electrum/network.py”, “electrum/blockchain.py”, and “electrum/daemon.py” handle connections to Bitcoin nodes, server lists, and blockchain data.
- Cryptography & External Dependencies: Integration with non-pure Python dependencies such as libsecp256k1 and the cryptography library for elliptic curve calculations and secure encryption.
- Plugin System: Located under “electrum/plugins”. This subsystem provides extensibility for hardware wallets (trezor, ledger, coldcard, digitalbitbox, etc.) and other additional functionalities.
- Supporting Components:
- Lightning network integration (modules like lnchannel.py, lnhtlc.py, lnurl.py, etc.).
- Helper utilities, internationalization (i18n), testing (the “tests” directory), and command line scripts (in “electrum/scripts”).
- Configurations and dependency management (setup.py, MANIFEST.in, configuration files) which support installation and building binaries.
- Build and Deployment Tools: The “contrib” directory contains build scripts and configurations for creating binaries across platforms (AppImage, Windows, macOS, Android).

##### Relationships and Interactions
- The GUI components (both Qt and QML) act as the front end, sending user commands to the core wallet and business logic modules.
- Core Wallet & Business Logic communicates with networking components to obtain blockchain data, broadcast transactions, and handle fee estimation.
- The Plugin System interacts with the core modules to add support for hardware wallet operations, label management, extra security measures, etc.
- Cryptography libraries (libsecp256k1, cryptography) operate as lower-level back-end services for encryption and transaction signing, and are used by the core wallet modules.
- Testing modules and scripts ensure that all of these components work cohesively, with unit tests covering interactions between these layers.

##### Architectural Patterns and Design Principles
- Modular Design: Electrum is split into clear modules (GUI, wallet, network, plugins) which encapsulates functionality.
- Separation of Concerns: The division between UI (presentation layer) and core wallet logic (business logic) ensures maintainability.
- Extensibility: Through its plugin architecture, Electrum allows third-party integrations and supports various external hardware wallets.
- Cross-Platform and Multi-Layered Build System: The “contrib” scripts and directories indicate a careful separation of platform-specific build and deployment configurations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% GUI Layer
    subgraph "GUI Layer"
        Qt["Qt GUI"]:::gui
        QML["QML GUI"]:::gui
    end

    %% Core Business Logic
    Core["Core Wallet & Business Logic"]:::core

    %% Backend Modules
    Network["Networking & Blockchain Interaction"]:::network
    Crypto["Cryptography Module"]:::crypto
    CryptoBuild["Crypto Build Integration"]:::crypto
    Plugin["Plugin System"]:::plugin
    Lightning["Lightning Network Integration"]:::lightning

    %% Supporting Components
    subgraph "Supporting Components"
        Testing["Testing"]:::support
        Scripts["Command Line Scripts"]:::support
    end

    %% Build & Deployment Tools
    Build["Build & Deployment Tools"]:::build

    %% Connections from GUI to Core
    Qt -->|"sends commands"| Core
    QML -->|"sends commands"| Core

    %% Core interactions with backend modules
    Core -->|"broadcasts_tx"| Network
    Core -->|"signs_tx_using"| Crypto
    Core -->|"integrates_with"| Plugin
    Core -->|"handles_LN"| Lightning

    %% Cryptography build support
    Build -->|"builds"| CryptoBuild
    CryptoBuild -->|"supports"| Crypto

    %% Supporting components interactions
    Testing -->|"verifies"| Core
    Scripts -->|"executes_cmds_on"| Core

    %% Build tools supporting overall project
    Build -->|"packages"| Core
    Build -->|"packages"| Plugin
    Build -->|"packages"| Network

    %% Styles
    classDef gui fill:#D0E6FF,stroke:#036,stroke-width:2px;
    classDef core fill:#FFF2CC,stroke:#B58900,stroke-width:2px;
    classDef network fill:#DCF8C6,stroke:#2E7D32,stroke-width:2px;
    classDef crypto fill:#F6CEE3,stroke:#D81B60,stroke-width:2px;
    classDef plugin fill:#E8EAF6,stroke:#303F9F,stroke-width:2px;
    classDef lightning fill:#E1F5FE,stroke:#039BE5,stroke-width:2px;
    classDef support fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px;
    classDef build fill:#E8F5E9,stroke:#43A047,stroke-width:2px;

    %% Click Events
    click Core "https://github.com/spesmilo/electrum/tree/master/electrum"
    click Qt "https://github.com/spesmilo/electrum/tree/master/electrum/gui/qt"
    click QML "https://github.com/spesmilo/electrum/tree/master/electrum/gui/qml"
    click Network "https://github.com/spesmilo/electrum/blob/master/electrum/network.py"
    click Crypto "https://github.com/spesmilo/electrum/blob/master/electrum/crypto.py"
    click CryptoBuild "https://github.com/spesmilo/electrum/tree/master/contrib/android/p4a_recipes/cryptography"
    click Plugin "https://github.com/spesmilo/electrum/tree/master/electrum/plugins"
    click Lightning "https://github.com/spesmilo/electrum/blob/master/electrum/lnchannel.py"
    click Testing "https://github.com/spesmilo/electrum/tree/master/tests"
    click Scripts "https://github.com/spesmilo/electrum/tree/master/electrum/scripts"
    click Build "https://github.com/spesmilo/electrum/tree/master/contrib"
```
