# koniverse/subwallet-extension architecture

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

## Overview

Based on our analysis of the file tree and the README, the project can be classified as a browser extension that is forked from polkadot-js/extension – a multi-part, full‐feature wallet and API integration tool for interacting with blockchain networks. Its primary purpose is to provide a rich interface (via a popup and portfolio page) for users to manage their blockchain accounts, while all major data processing (including API calls, state persistence, cronjobs, and message handling) is centralized in the background environment. It also supports injected scripts into web pages to provide long-term data interoperability with participating DApps.

##### Main Components
- Background Environment:
– Represented by the “extension-koni” package.
– Contains the central background script (packages/extension-koni/src/background.ts) that handles Chrome API message passing, persistent state management (via stores that extend BaseStore/ SubscribableStore), and periodic cron jobs.
– Responsible for all API calls to external blockchain services, processing data, and serving it to page layers.
- Messaging Layer:
– Illustrate message channels between the background service and extension pages (such as the popup).
– Include both “one time” and “subscription” message types defined in the code (e.g., in the KoniRequestSignatures interfaces).
- User Interface:
– The UI is built with ReactJS and is packaged as “extension-koni-ui” (and also “extension-web-ui” for similar web entry points).
– UI components, redux store integration (via redux-toolkit), and hooks compose this layer.
- Injection Layer:
– The “extension-inject” package handles the injection of scripts into Chrome tabs so that web pages (i.e., dApps) can access the background API indirectly.
- Auxiliary & API Wrappers:
– “extension-dapp” is a convenience wrapper for dApp developers.
– “extension-chains” holds definitions and simplified metadata for supported chains.
– “extension-compat-metamask” provides compatibility with Metamask.
– “extension-mocks” and “subwallet-api-sdk” support testing and external SDK interfaces.
- Cron Jobs and Store Persistence:
– Show that the background layer includes cron management (in packages/extension-koni-base/src/cron) and a state management system (stores, persisting data to chrome storage).

##### Relationships & Data Flow
- That all API requests and data modifications occur only via the background service.
- That the injected scripts and the UI do not directly call third-party APIs; instead, they communicate with the background.

##### Architectural Patterns & Design Principles
- Clear separation between presentation (UI) and business logic (background, message handling).
- Use of a central store (KoniState and redux store slices) for state persistence.
- Messaging abstraction layers that enable one-time requests and subscription-based communication.
- Modularity: The project is split into packages (each with a distinct purpose such as “extension-koni”, “extension-koni-ui”, “extension-dapp”, etc.) ensuring that improvements or rebasing from the upstream polkadot-js extension can be easily integrated.
- Dependency injection and separation of concerns: the API layer (in “extension-koni-base”) encapsulates API calls and message handling.

##### Relevant Technologies and Frameworks
- ReactJS (for building extension pages).
- Redux Toolkit (for managing global state in the UI).
- TypeScript (for static typing across all packages).
- Chrome Extension APIs (for message passing, storage, and injection).
- Additional libraries such as rxjs in SubscribableStore, and jest for testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        A1("Popup Page (extension-koni-ui)"):::ui
        A2("Popup Page (extension-web-ui)"):::ui
        A3("Portfolio Page (UI)"):::ui
    end

    subgraph "Injection Layer"
        B1("Injection Scripts (extension-inject)"):::injection
    end

    subgraph "Messaging Layer"
        C1("Messaging (extension-koni-ui)"):::messaging
    end

    subgraph "Core Background"
        D1("Background Script (extension-koni)"):::background
        D2("Background Init (extension-koni)"):::background
        D3("Cron Jobs & Store Persistence"):::background
    end

    subgraph "Auxiliary & API Wrappers"
        E1("dApp API Wrapper (extension-dapp)"):::auxiliary
        E2("Chains Definitions (extension-chains)"):::auxiliary
        E3("Metamask Compatibility (extension-compat-metamask)"):::auxiliary
        E4("Mocks & Testing (extension-mocks)"):::auxiliary
        E5("External SDK (subwallet-api-sdk)"):::auxiliary
    end

    %% Relationships
    A1 -->|"MessagePassing"| C1
    A2 -->|"MessagePassing"| C1
    A3 -->|"MessagePassing"| C1

    C1 -->|"MessagePassing"| D1
    B1 -->|"MessagePassing"| D1

    D1 -->|"Initialize"| D2
    D1 -->|"Triggers"| D3

    D1 -->|"APIcalls"| E1
    D1 -->|"APIcalls"| E2
    D1 -->|"APIcalls"| E3
    D1 -->|"APIcalls"| E4
    D1 -->|"APIcalls"| E5

    %% Click Events
    click D1 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-koni/src/background.ts"
    click D2 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-koni/src/background-init.ts"
    click C1 "https://github.com/koniverse/subwallet-extension/tree/master/packages/extension-koni-ui/src/messaging"
    click A1 "https://github.com/koniverse/subwallet-extension/tree/master/packages/extension-koni-ui/src/Popup"
    click A2 "https://github.com/koniverse/subwallet-extension/tree/master/packages/extension-web-ui/src/Popup"
    click B1 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-inject/src/index.ts"
    click E1 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-dapp/src/index.ts"
    click E2 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-chains/src/index.ts"
    click E3 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-compat-metamask/src/index.ts"
    click E4 "https://github.com/koniverse/subwallet-extension/blob/master/packages/extension-mocks/src/chrome.ts"
    click E5 "https://github.com/koniverse/subwallet-extension/blob/master/packages/subwallet-api-sdk/src/sdk.ts"

    %% Styles
    classDef ui fill:#a8e6cf,stroke:#348017,stroke-width:2px,color:#000;
    classDef messaging fill:#ffeb3b,stroke:#fbc02d,stroke-width:2px,color:#000;
    classDef background fill:#81d4fa,stroke:#039be5,stroke-width:2px,color:#000;
    classDef injection fill:#ffcc80,stroke:#f57c00,stroke-width:2px,color:#000;
    classDef auxiliary fill:#d1c4e9,stroke:#673ab7,stroke-width:2px,color:#000;
```
