# cardware-wallet/cardware-btc architecture

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

- Interactive diagram: https://gitdiagram.com/cardware-wallet/cardware-btc
- Repository: https://github.com/cardware-wallet/cardware-btc

## Overview

##### Main Components
- Web Wallet Frontend: This is the user-facing layer (typically a browser application) that imports the NPM package and interacts with it.
- Cardware BTC NPM Library: Represented by the package generated under the “pkg” directory (including JavaScript bindings and WASM modules). This library is the bridge between the web wallet and the Cardware hardware.
- Rust Source Code: The “src” directory houses the core Rust implementation (lib.rs and main.rs) that compiles to WebAssembly. This is the heart of the business logic.
- Cardware Device: The physical hardware wallet that communicates via QR codes to sign transactions and provide public keys (zpub).
- Electrs/Bitcoin Blockchain Interface: The external electrs endpoint is used by the library to query blockchain data, fee estimations, and broadcast transactions.

##### Relationships and Interactions
- The Web Wallet calls into the Cardware BTC library (via standard JavaScript imports, as shown in the README code samples).
- The Library (WASM module wrapped in a JavaScript interface) processes wallet operations, including pairing, fee estimation, and transaction creation.
- Data Transfer via QR Code: For both sending unsigned transactions and receiving signed transactions from the Cardware device, information is split into QR code chunks. Represent this bidirectional flow between the library and the hardware wallet.
- API Communication: The library interacts with an electrs endpoint for blockchain queries (e.g., syncing balances, fee estimates) and for broadcasting signed transactions.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The separation between the frontend (web wallet UI), the core wallet logic (Rust/WASM library), and external blockchain services.
- Modular Design: Clear responsibility for each component—from transaction construction in the library to user interactions and QR code scanning in the web wallet.
- Security via Offline Device Signing: Emphasize that the signing process is split between the web wallet (which constructs unsigned transactions) and the Cardware device (which securely signs transactions offline through QR codes).
- Data Flow Transparency: The QR code-based communication mechanism should be clearly delineated in the system design, emphasizing the extra metadata (QR code indexing) used for reconstruction.

##### Relevant Technologies
- Rust and WebAssembly: Underlying implementation technology that powers the wallet logic.
- JavaScript/TypeScript Bindings: Exposed by the NPM package (located in “pkg”) for integration with web applications.
- QR Code Mechanism: Used for the secure exchange of transaction data between the web wallet and the Cardware device.
- External API: The electrs endpoint (or similar Bitcoin blockchain query API) used for balance synchronization and fee estimations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    WebWallet["Web Wallet Frontend"]:::frontend
    Library["Cardware BTC NPM Library"]:::library
    RustSource["Rust Source Code"]:::rust
    Electrs["Electrs API/Bitcoin Blockchain"]:::external
    CardwareDevice["Cardware Device (Hardware Wallet)"]:::hardware

    WebWallet -->|"calls"| Library
    Library -->|"compiled_from"| RustSource
    Library <-->|"blockchain_comms"| Electrs
    Library <-->|"QRCode_exchange"| CardwareDevice

    click Library "https://github.com/cardware-wallet/cardware-btc/tree/main/pkg/"
    click RustSource "https://github.com/cardware-wallet/cardware-btc/tree/main/src/"

    classDef frontend fill:#D1E8FF,stroke:#333,stroke-width:2px;
    classDef library fill:#FFECB3,stroke:#333,stroke-width:2px;
    classDef rust fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#333,stroke-width:2px;
    classDef hardware fill:#F0F4C3,stroke:#333,stroke-width:2px;
```
