# bob-collective/sats-wagmi architecture

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

- Interactive diagram: https://gitdiagram.com/bob-collective/sats-wagmi
- Repository: https://github.com/bob-collective/sats-wagmi

## Overview

##### Project’s Core Purpose and Type
- This project is a specialized library (or SDK) that abstracts the integration of multiple BTC wallet connectors. It mirrors the pattern used by the popular “wagmi” library for Ethereum but targets Bitcoin.
- Its two main facets are the wallet connector implementations and a set of React hooks that provide an interface to developers, along with a provider component (SatsWagmiConfig) that the app wraps for context/state management.

##### File Structure for Architectural Clues
- Top-Level Directories:
- packages: Contains the core sats-wagmi library in the sats-wagmi package. Within it, structured subdirectories like “assets”, “connectors”, “hooks”, “constants”, and “utils” indicate a clear separation of concerns.
- playgrounds: Provides demo applications (e.g., a Vite React playground) to demonstrate the integration and usage of the library.
- Configuration files and GitHub workflows: Suggest an emphasis on code quality, testing, and continuous integration but are not central to the runtime architecture.
- Within “packages/sats-wagmi/src”:
- “connectors” directory: Hosts different wallet connector implementations (e.g., for MMSnap, Leather, Unisat, Xverse, Bitget, OKX Wallet).
- “hooks” directory: Contains React hook implementations such as useConnect, useAccount, among others.
- “provider.tsx”: Likely to export the configuration provider (SatsWagmiConfig) that manages state and context for the hook consumers.
- “assets”, “constants”, and “utils”: Support the core functionality (e.g., handling network-specific logic or reusable utility functions).

##### Main Components
a. Library Core:
- SatsWagmi Provider (SatsWagmiConfig): The top-level context provider for React applications.
- React Hooks: These include useConnect, useAccount, useFeeEstimate, etc., which expose wallet functionalities to the developer.
b. Wallet Connector Modules:
- Individual connector implementations (MMSnapConnector, Leather, Unisat, etc.) that abstract the connection logic and communication with external BTC wallets.
- Asset modules that might hold chain-specific or wallet-specific configuration files (bitget.ts, okx.ts).
c. Supporting Utilities:
- Constants and utility functions used by both connectors and hooks.
d. Demo/Playground:
- The playground app (using Vite React) to exemplify library usage.
e. Testing and Configuration (for reference):
- Though not central to runtime architecture, mention test files and configuration scripts as supporting tools ensuring quality in development.

##### Relationships and Data Flow
- The SatsWagmi Provider (SatsWagmiConfig) wraps the application and supplies context to the React hooks.
- The React Hooks interact with the respective wallet connector implementations. For example:
- useConnect hook fetches available connectors and interacts with them to establish connections.
- Once a connection is established, further hooks (like useAccount) retrieve BTC account data or perform transactions.
- Connector modules encapsulate the logic to interact with external BTC wallet APIs or browser extensions.
- Utility functions and constants support data transformations and configuration across modules.

##### Detailing Architectural Design Patterns and Principles
- Separation of concerns:
- The provider manages the configuration and state, hooks expose interaction points, and connectors encapsulate wallet-specific logic.
- Modularity:
- Each connector is isolated; new connectors can be added without changing the rest of the system.
- Reusability and testability:
- The structure supports isolated testing (note the test directories under connectors) and easy integration into any React interface.

## Diagram (Mermaid)

```mermaid
graph TD
    D["Demo App (Playgrounds - Vite React)"]:::demo
    E["External BTC Wallet/APIs"]:::external

    subgraph "SatsWagmi Library"
        subgraph "React Integration Layer"
            P["Provider (SatsWagmiConfig)"]:::react
            H["React Hooks (useConnect, useAccount, etc.)"]:::react
            P -->|"provides_context"| H
        end
        subgraph "Wallet Connector Layer"
            CW1["MMSnapConnector"]:::connector
            CW2["Leather Connector"]:::connector
            CW3["OKX Connector"]:::connector
            CW4["Unisat Connector"]:::connector
            CW5["Xverse Connector"]:::connector
            H -->|"calls_connector"| CW1
            H -->|"calls_connector"| CW2
            H -->|"calls_connector"| CW3
            H -->|"calls_connector"| CW4
            H -->|"calls_connector"| CW5
            CW1 -->|"interacts"| E
            CW2 -->|"interacts"| E
            CW3 -->|"interacts"| E
            CW4 -->|"interacts"| E
            CW5 -->|"interacts"| E
        end
        subgraph "Support Modules"
            A["Asset Modules"]:::support
            C["Constants"]:::support
            U["Utility Functions"]:::support
            H -->|"uses_support"| A
            H -->|"uses_support"| C
            H -->|"uses_support"| U
            CW1 -->|"uses_support"| A
            CW1 -->|"uses_support"| C
            CW1 -->|"uses_support"| U
            CW2 -->|"uses_support"| A
            CW2 -->|"uses_support"| C
            CW2 -->|"uses_support"| U
            CW3 -->|"uses_support"| A
            CW3 -->|"uses_support"| C
            CW3 -->|"uses_support"| U
            CW4 -->|"uses_support"| A
            CW4 -->|"uses_support"| C
            CW4 -->|"uses_support"| U
            CW5 -->|"uses_support"| A
            CW5 -->|"uses_support"| C
            CW5 -->|"uses_support"| U
        end
    end

    D -->|"wraps_in"| P

    click P "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/provider.tsx"
    click H "https://github.com/bob-collective/sats-wagmi/tree/main/packages/sats-wagmi/src/hooks/"
    click CW1 "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/connectors/mm-snap.ts"
    click CW2 "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/connectors/leather.ts"
    click CW3 "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/connectors/okx.ts"
    click CW4 "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/connectors/unisat.ts"
    click CW5 "https://github.com/bob-collective/sats-wagmi/blob/main/packages/sats-wagmi/src/connectors/xverse.ts"
    click A "https://github.com/bob-collective/sats-wagmi/tree/main/packages/sats-wagmi/src/assets/"
    click C "https://github.com/bob-collective/sats-wagmi/tree/main/packages/sats-wagmi/src/constants/"
    click U "https://github.com/bob-collective/sats-wagmi/tree/main/packages/sats-wagmi/src/utils/"
    click D "https://github.com/bob-collective/sats-wagmi/tree/main/playgrounds/vite-react"

    classDef react fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef connector fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef support fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef demo fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px;
```
