# leather-io/extension architecture

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

- Interactive diagram: https://gitdiagram.com/leather-io/extension
- Repository: https://github.com/leather-io/extension

## Overview

##### Project type and purpose
- Leather is a browser extension (Web Extension) implementing a crypto wallet for Bitcoin, Bitcoin L2s, and the Stacks blockchain. It offers a popup UI, in-page injection, background processing, messaging APIs (RPC), and integrates with hardware wallets (Ledger).

##### File structure
- Top-level “src” children define extension contexts:
- src/app – React/TypeScript UI for popup/extension pages (popup, dev-tool, onboarding, send/receive, swap, settings, etc.). Uses Redux for state, React Query (via src/query) for external data.
- src/background – background service worker handling long-running tasks: message routing, RPC method handlers, monitors (address updates, websockets).
- src/content-scripts – injected script for page context to hook dapps.
- src/inpage – small script injected into the page to define the `window?.leather` API, forwarding calls to the background.
- src/shared – code shared across contexts (RPC schemas, crypto, storage helpers, message types, utilities).
- Other key folders:
- public – static assets and HTML entrypoints for each extension page.
- test-app – standalone React app to test extension RPC APIs.
- tests – Playwright integration tests for extension UI + test-app, plus unit tests (Vitest).
- scripts, config, webpack, package.json, CI workflows for building, linting, testing, publishing.

##### README for additional insights
- Confirms it’s a Web Extension (MV3) targeting Chrome/Firefox.
- Describes contexts cannot run standalone – must be loaded as an extension.
- Mentions test-app for quick API tests.
- Outlines development commands, build targets, and testing.

##### Main components
a. Extension UI (src/app)
- Popup & React pages
- Redux store
- Query clients (REST/fetch to external Bitcoin/Stacks/market-data/compliance APIs)
b. Background Service Worker (src/background)
- RPC message handler
- Internal message broker
- Address monitors (mempool WebSocket)
- Chrome.storage persistence
c. Content Script (src/content-scripts)
- Injected into dapp pages to listen for hook calls
d. Inpage Script (src/inpage)
- Injected before page loads, exposes window API to dapps, forwards to background
e. Shared Modules (src/shared)
- RPC schemas & types
- Crypto & encryption utilities
- Message-type definitions
- Storage & persistence logic
f. External Services
- Bitcoin node or explorer APIs (UTXOs, broadcast, fee estimates)
- Stacks node or explorer APIs (transactions, contracts, mempool)
- Market data vendors (Binance, Coingecko, Coincap)
- Compliance checker, remote configs, sponsored transactions API, bitflow SDK
g. Hardware Wallet Integration
- Ledger flows (USB/HID) via background and UI

##### Relationships and interactions
- Dapp → (inpage) → window.leather API → chrome.runtime.sendMessage → background → UI/data/store or RPC → background calls external API → background returns result → UI or inpage
- UI ↔ background via chrome.runtime messaging for state changes, transaction signing, key requests.
- Background monitors chain updates (WebSocket), updates Redux store via messaging to UI or triggers notifications.
- Content script detects dapp contexts, optionally shows UI cues or intercepts calls.
- Test-app communicates via same RPC channels to background service.

##### Architectural patterns and design principles
- Single-page React apps for each extension page (popup, dev-tool, debug).
- Unidirectional data flow: UI dispatches actions → Redux → side effects via thunks/hooks → background/external.
- Messaging bus pattern for cross-context communication.
- Context isolation: UI vs. background vs. content vs. inpage.
- Modular “shared” layer to prevent duplication and maintain type safety across bundles.

##### Detail
- Every context as a separate “service” node
- Internal RPC bus and shared schemas
- Interactions with both Bitcoin and Stacks networks, plus ancillary APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Dapp & Injection"
        direction TB
        DAPP["Dapp Web Page"]:::external
        INPAGE["Inpage Script"]:::blue
        CONTENT["Content Script"]:::blue
    end

    subgraph "Extension Contexts"
        direction TB
        UI["Extension UI"]:::blue
        STORE["Redux Store"]:::persistence
        QUERY["React Query Clients"]:::blue
        BG["Background Service Worker"]:::blue
        BROKER["Internal Message Broker"]:::blue
        RPCHANDLERS["RPC Method Handlers"]:::blue
        MONITORS["Address Monitors"]:::blue
    end

    subgraph "Shared Modules"
        direction TB
        SHARED_RPC["RPC Schemas & Types"]:::shared
        SHARED_CRYPTO["Crypto Utilities"]:::shared
        SHARED_MSG["Message Types & Actions"]:::shared
        SHARED_STORAGE["Storage Helpers"]:::shared
    end

    subgraph "External & Hardware"
        direction TB
        BTC_API["Bitcoin Node/Explorer"]:::external
        STACKS_API["Stacks Node/Explorer"]:::external
        MARKET["Market Data APIs"]:::external
        COMPLIANCE["Compliance & Config"]:::external
        HARDWARE["Ledger Integration"]:::hardware
    end

    subgraph "Testing & CI"
        direction TB
        TESTAPP["Test Application"]:::blue
        INTEG["Playwright Integration Tests"]:::blue
        UNIT["Vitest Unit Tests"]:::blue
        CI["CI & Build Workflows"]:::blue
    end

    DAPP -->|"window.leather API"| INPAGE
    INPAGE -->|"RPC messages"| BG
    CONTENT -->|"dapp hooks & cues"| BG
    UI -->|"chrome.runtime.sendMessage"| BG
    BG -->|"push state updates"| UI
    BG -->|"HTTP/WS calls"| BTC_API
    BG -->|"HTTP/WS calls"| STACKS_API
    BG -->|"HTTP/WS calls"| MARKET
    BG -->|"HTTP/WS calls"| COMPLIANCE
    BG -->|"WebSocket updates"| MONITORS
    MONITORS -->|"chain updates"| BG
    BG -->|"updates"| STORE
    STORE -->|"state"| UI
    UI -->|"uses"| QUERY
    UI -->|"hardware flows"| HARDWARE
    BG -->|"RPC bus"| BROKER
    BROKER -->|"dispatch"| RPCHANDLERS
    RPCHANDLERS -->|"uses"| SHARED_RPC
    BG -->|"uses"| SHARED_CRYPTO
    BG -->|"uses"| SHARED_MSG
    BG -->|"uses"| SHARED_STORAGE
    TESTAPP -->|"RPC channels"| BG
    CI -->|"builds"| UI
    CI -->|"builds"| BG
    CI -->|"builds"| CONTENT
    CI -->|"builds"| INPAGE
    INTEG -->|"tests UIs"| UI
    UNIT -->|"tests modules"| SHARED_RPC
    UNIT -->|"tests modules"| SHARED_CRYPTO
    UNIT -->|"tests modules"| SHARED_MSG
    UNIT -->|"tests modules"| SHARED_STORAGE

    click UI "https://github.com/leather-io/extension/tree/dev/src/app"
    click STORE "https://github.com/leather-io/extension/tree/dev/src/app/store"
    click QUERY "https://github.com/leather-io/extension/tree/dev/src/app/query"
    click BG "https://github.com/leather-io/extension/blob/dev/src/background/background.ts"
    click RPCHANDLERS "https://github.com/leather-io/extension/tree/dev/src/background/messaging/rpc-methods"
    click BROKER "https://github.com/leather-io/extension/blob/dev/src/background/messaging/rpc-message-handler.ts"
    click MONITORS "https://github.com/leather-io/extension/tree/dev/src/background/monitors"
    click CONTENT "https://github.com/leather-io/extension/blob/dev/src/content-scripts/content-script.ts"
    click INPAGE "https://github.com/leather-io/extension/blob/dev/src/inpage/inpage.ts"
    click SHARED_RPC "https://github.com/leather-io/extension/blob/dev/src/shared/rpc/rpc-schemas.ts"
    click SHARED_CRYPTO "https://github.com/leather-io/extension/tree/dev/src/shared/crypto"
    click SHARED_MSG "https://github.com/leather-io/extension/blob/dev/src/shared/message-types.ts"
    click SHARED_STORAGE "https://github.com/leather-io/extension/tree/dev/src/shared/storage"
    click HARDWARE "https://github.com/leather-io/extension/tree/dev/src/app/features/ledger"
    click TESTAPP "https://github.com/leather-io/extension/tree/dev/test-app"
    click INTEG "https://github.com/leather-io/extension/tree/dev/tests/specs"
    click UNIT "https://github.com/leather-io/extension/tree/dev/tests/unit"
    click CI "https://github.com/leather-io/extension/blob/dev/.github/workflows/build-extension.yml"

    classDef blue fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef shared fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef persistence fill:#D3D33,stroke:#000,stroke-width:1px;
    classDef hardware fill:#DDA0DD,stroke:#000,stroke-width:1px;
```
