# block-wallet/extension architecture

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

## Overview

##### Main Components
- Background Service (packages/background):
– Implements various controllers (e.g., AccountTracker, NetworkController, GasPricesController) and infrastructure layers like storage, hardware integration (e.g., Trezor), migrations, and utilities.
– Handles core wallet logic such as account management, transaction handling, and blockchain interactions.
- Provider (packages/provider):
– Acts as a bridge between the wallet extension and DApps by providing an injected provider.
– Manages communication, compatibility shims (like shimWeb3), and error handling for dApp interactions.
- User Interface (packages/ui):
– Contains a full React-based front end including an app component, numerous UI components, routes for various use cases (account management, sending transactions, settings, swap flows, etc.), and styles (tailwindcss is used).
– Drives popups, account displays, dialogs, notifications, and overall user experience.
- Browser Integration & Manifest:
– The root includes manifest files (for Chrome and Firefox) and public assets. These define how the extension is integrated into the browser.
- External Dependencies and Services:
– External APIs like Etherscan (as noted in environment variables) supporting blockchain queries, and interactions with blockchain networks.
- Build/CI Infrastructure:
– GitHub workflows (build, CI, release) and Makefiles which indicate continuous integration and deployment processes.

##### Out the Relationships & Interactions
- The UI (React front end) communicates with the Background service via message passing or API calls within the extension context.
- The Provider is injected into web pages (dApps), relaying requests from these applications to the Background service.
- The Background service, serving as the central logic hub, handles blockchain operations, interacts with external APIs (such as Etherscan), and manages internal states through controllers and stores.
- Each package is developed somewhat independently (with its own .env and configs) but communicates to fulfill the overall wallet functionality.

##### Architectural Patterns & Design Principles
- Modularity: Separation into distinct packages for background scripts, provider logic, and UI.
- MVC-Inspired Pattern: Background services use “controllers” and “stores” to manage state and business logic, and the UI renders views based on that state.
- Decoupled Communication: Use of message-passing between the UI and background processes, and an injected provider to interface with DApps.
- Test-Driven: Extensive test folders in each package promote clear contracts and reliable functionality.

##### Relevant Technologies
- Node.js, Typescript, React.js, and tailwindcss for the UI.
- Webpack is employed in both the Background and Provider (and UI) packages for bundling.
- Yarn and Make are used for dependency management and scripts.
- GitHub workflows are used for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    D("Browser Environment<br/>(Manifest & Public Assets)"):::browser
    UI("UI (React Components & Routes)"):::ui
    P("Provider (dApp Bridge & Compatibility Layer)"):::provider
    B("Background Service<br/>(Controllers, Stores, Utilities)"):::background
    E("External Services<br/>(Blockchain Networks, Etherscan APIs)"):::external
    F("Build/CI Infrastructure<br/>(GitHub Workflows & Makefiles)"):::build

    D -->|"loadsUI"| UI
    D -->|"injectsProvider"| P
    UI -->|"triggers"| B
    P -->|"dAppRequests"| B
    B -->|"apiCalls"| E
    F -->|"supports"| UI
    F -->|"supports"| P
    F -->|"supports"| B

    click B "https://github.com/block-wallet/extension/tree/master/packages/background"
    click P "https://github.com/block-wallet/extension/tree/master/packages/provider"
    click UI "https://github.com/block-wallet/extension/tree/master/packages/ui"
    click D "https://github.com/block-wallet/extension/blob/master/manifest/base.json"
    click D "https://github.com/block-wallet/extension/tree/master/public"
    click F "https://github.com/block-wallet/extension/tree/master/.github/workflows"
    click F "https://github.com/block-wallet/extension/tree/master/Makefile"

    classDef ui fill:#CFFFCF,stroke:#333,stroke-width:2px;
    classDef provider fill:#E6E6FF,stroke:#333,stroke-width:2px;
    classDef background fill:#FFE6E6,stroke:#333,stroke-width:2px;
    classDef browser fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef external fill:#F3E5F5,stroke:#333,stroke-width:2px;
    classDef build fill:#E0E0E0,stroke:#333,stroke-width:2px;
```
