# thorswap/swapkit architecture

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

- Interactive diagram: https://gitdiagram.com/thorswap/swapkit
- Repository: https://github.com/thorswap/swapkit

## Overview

##### Project’s Main Purpose and Components
- Project Purpose: SwapKit is designed to “Integrate Blockchains easily” by providing modular packages for interacting with various blockchains, wallets, and other blockchain-related services.
- Major Components:
- SwapKit Core/SDK: The heart of the project with core client logic, helper functions, and API integrations.
- Plugins: Individual modules under packages/plugins (e.g. chainflip, evm, kado, radix, thorchain) that are responsible for specific blockchain or protocol integrations.
- Contracts: Contract packages under packages/swapkit/contracts which manage ABIs, routers, and contract interactions.
- APIs: The swap kit API under packages/swapkit/api which likely wraps multiple endpoints such as midgard, microgard, and other chain endpoints.
- Helpers: Packages/swapkit/helpers that provide common utility functions and type definitions.
- Wallets: A collection of packages (in packages/wallets) that integrate with a variety of wallet providers (e.g. coinbase, ledger, keplr, trezor, etc.).
- Toolboxes: Framework-specific helper packages found under packages/toolboxes (for Cosmos, EVM, Radix, Solana, Substrate, UTXO) that contain chain-specific logic and APIs.
- Tokens: The packages/swapkit/tokens that handle token lists and token-related operations.
- Wizard: A CLI/template tool (packages/swapkit/wizard) that likely simplifies scaffolding or setup.
- Playgrounds: Demo / testing applications (playgrounds/nextjs, playgrounds/node, playgrounds/vite) that demonstrate how to integrate and use SwapKit.
- Tools and Scripts: Additional directories (tools, scripts) for building, testing, versioning (changesets), and repository management.

##### Relationships and Interactions
- The SwapKit Core/SDK interfaces with the plugins, APIs, and contract modules, ensuring a central point of integration.
- Plugins are responsible for integrating specific blockchain protocols, so they depend on the core for common functionality, while exposing protocol-specific features.
- The Wallet packages offer connectors for different wallet types and interact either directly with the core or via supporting toolboxes.
- Toolboxes provide environment-specific or blockchain-specific utilities and wrap client libraries that the wallets and plugins can use.
- The API and Contracts layers expose endpoints and blockchain interactions to the higher-level SDK and/or UI components found in playgrounds.
- Playgrounds act as client-side applications, demonstrating usage of the core, plugins, and wallet integrations.
- Tools and scripts support automated building, testing, releasing, and version management across all packages.

##### Architectural Patterns and Design Principles
- Modular Design: Each package (core, plugins, wallets, toolboxes, etc.) is isolated, making it easier to update and extend.
- Clear Separation of Concerns: The code is grouped by functionality—API, contracts, core logic, wallets, toolboxes—allowing developers to focus on one aspect.
- Dependency Management: Leveraging package.json files and build scripts ensures that different modules have clearly defined dependencies.
- Extensibility & Scalability: The design supports new blockchain integrations and wallet support by simply adding new packages/modules without affecting the overall architecture.

##### Relevant Technologies, Frameworks, and Libraries
- Language/Runtime: TypeScript (indicated by tsconfig.json files) and Bun (modern JavaScript runtime, as shown in installation docs).
- Tools: Changesets for version management, GitHub Actions to automate CI/CD, and ESLint for code quality.
- UI Frameworks: For playgrounds, frameworks such as Next.js and Vite (demonstrated by playground structure) are used for example applications.
- Blockchain-specific libraries and APIs: The project integrates with many blockchain networks (EVM, Cosmos, etc.) and wallet providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Client Applications
    P["Playgrounds<br/>(Demo Apps: nextjs, node, vite)"]:::playgrounds

    %% Middle Layer: Core SDK and Modules
    C["SwapKit Core/SDK<br/>(Central SDK providing APIs for blockchain integration)"]:::sdk

    subgraph Modules [ ]
        PL["Plugins<br/>(chainflip, evm, kado, radix, thorchain)"]:::plugins
        CO["Contracts<br/>(ABIs, routers, contract interactions)"]:::contracts
        API["APIs<br/>(SwapKit API endpoints)"]:::api
        HE["Helpers<br/>(Utility functions & type definitions)"]:::helpers
        WA["Wallets<br/>(Wallet providers: coinbase, ledger, keplr, trezor, etc.)"]:::wallets
        TB["Toolboxes<br/>(Cosmos, EVM, Radix, Solana, Substrate, UTXO)"]:::toolboxes
        TO["Tokens<br/>(Token lists and operations)"]:::tokens
        WZ["Wizard<br/>(CLI/Template tool for scaffolding)"]:::wizard
    end

    %% Bottom Layer: Dev & Build Tools
    TS["Tools & Scripts<br/>(Building, testing, versioning, CI/CD)"]:::tools

    %% Connections: Data Flow and Dependencies

    %% Client Layer to Core
    P -->|"uses"| C

    %% Core to Modules
    C -->|"integrates"| PL
    C -->|"manages"| CO
    C -->|"wraps"| API
    C -->|"utilizes"| HE
    C -->|"connects with"| WA
    C -->|"depends on"| TB
    C -->|"handles"| TO
    C -->|"supports"| WZ

    %% Additional Relationships
    P -->|"demonstrates usage"| WA
    P -->|"interfaces with"| API

    WA -->|"leverages"| TB

    %% Tools and Scripts support Core functionality
    TS -->|"supports"| C

    %% Click Events
    click P "https://github.com/thorswap/swapkit/tree/develop/playgrounds"
    click C "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/core"
    click PL "https://github.com/thorswap/swapkit/tree/develop/packages/plugins"
    click CO "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/contracts"
    click API "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/api"
    click HE "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/helpers"
    click WA "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/wallets"
    click TB "https://github.com/thorswap/swapkit/tree/develop/packages/toolboxes"
    click TO "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/tokens"
    click WZ "https://github.com/thorswap/swapkit/tree/develop/packages/swapkit/wizard"
    click TS "https://github.com/thorswap/swapkit/tree/develop/tools and scripts"

    %% Styles
    classDef sdk fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef plugins fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef contracts fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef api fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef helpers fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef wallets fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef toolboxes fill:#e8eaf6,stroke:#283593,stroke-width:2px;
    classDef tokens fill:#f1f8e9,stroke:#558b2f,stroke-width:2px;
    classDef wizard fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef playgrounds fill:#fffde7,stroke:#f9a825,stroke-width:2px;
    classDef tools fill:#eceff1,stroke:#37474f,stroke-width:2px;
```
