# koniverse/subwallet-mobile architecture

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

- Interactive diagram: https://gitdiagram.com/koniverse/subwallet-mobile
- Repository: https://github.com/koniverse/subwallet-mobile

## Overview

##### Project Type and Purpose
- This is a cross-platform mobile application (iOS & Android) built with React Native that surfaces the functionality of the SubWallet browser extension in a mobile context.
- To overcome React Native’s lack of WebAssembly support and to share the same Polkadot crypto libraries with the extension, most blockchain logic runs inside a hidden WebView (“WebRunner”), and React Native communicates with it via message passing.

##### High-Level File Structure Overview
- **android/** / **ios/** – Native platform projects (build.gradle, Xcode).
- **html/** – Prebuilt WebRunner bundles (WASM + JS) loaded in WebView.
- **src/** – React Native code: screens, components, hooks, providers, stores, utils.
- **scripts/** – Build & CI/CD scripts (build-android, build-ios, upload).
- **stores/** & **reducers/** – State management layer.
- **providers/** – React Context providers wrapping UI and WebRunner.
- **messaging/** – Message-passing definitions between React Native host and WebRunner guest.
- **nativeModules/** – Custom native bridges (e.g., RCTMinimizer).

##### Architecture Overview from README
- React Native hosts a hidden WebView (“app runner” / WebRunner) that loads Polkadot/WebRunner assets.
- UI layer dispatches commands and listens for events over a bidirectional messaging channel to perform crypto operations, network calls, transaction signing, etc.
- This maintains one codebase for shared logic (extension vs mobile).

##### Key Components
a. **UI Layer (React Native App):**
- Screens & Components (src/screens/, src/components/)
- Navigation (src/AppNavigator.tsx)
- Context Providers (AppModalContext, TransactionContext, WebRunnerProvider)
- State Management (stores/, reducers/)

b. **WebRunner (Hidden WebView):**
- Loads pre-compiled HTML/JS/WASM bundles from html/Web.bundle
- Holds Polkadot JS and WASM modules (@polkadot packages)
- Exposes an RPC-style message API to React Native

c. **Native Modules & Services:**
- RCTMinimizer, StaticServer (custom native bridges)
- Secure storage (AsyncStorage or Keychain)
- Camera / QR scanner modules

d. **External Services:**
- Dotsama node RPC endpoints (Polkadot/Substrate networks)
- 3rd-party buy providers (Banxa, Coinbase, Transak)

##### Interactions & Data Flow
1. **User Action → UI**
- User taps UI → React Native event handler → dispatches action (via context or store).
2. **UI → WebRunner**
- Host posts a message to WebView containing the JSON-RPC request (e.g., fetch balance, sign transaction).
3. **WebRunner Processing**
- WebRunner JS/WASM executes Polkadot logic, fetches data from chain RPC, signs payload.
4. **WebRunner → UI**
- WebRunner posts a response message back to React Native with the result or error.
5. **UI Updates State & Renders**
- Message handler in providers updates stores/reducers, React re-renders components.
6. **Native Services**
- For camera/QR or local file storage, React Native calls custom native modules directly.

##### Architectural Patterns & Principles
- **Flux-style state management:** centralized stores + reducers, accessed via React Context.
- **Message-passing boundary:** explicit separation of crypto logic into WebView.
- **Component hierarchy:** Presentation (screens/components) ←→ Context/Providers ←→ Stores ←→ WebRunner/Native Modules.
- **Separation of concerns:** UI, business logic (hooks/services), state management, external communication.

##### Technologies & Frameworks
- React Native (JS/TS)
- React Navigation
- React Context & Hooks
- Custom state layer (stores + reducers)
- WebRunner (hidden WebView + WASM bundles)
- Native Modules (Java/Objective-C bridges)
- Yarn, Metro, Babel, CMake (for WASM build)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer" 
        direction TB
        Root["Root (src/Root.tsx)"]:::ui
        App["App (src/App.tsx)"]:::ui
        Navigator["AppNavigator (src/AppNavigator.tsx)"]:::ui
        Screens["Screens (src/screens/)"]:::ui
        Components["Components (src/components/)"]:::ui
    end

    subgraph "State & Context Layer"
        direction TB
        ModalCtx["AppModalContext Provider"]:::state
        TxCtx["TransactionContext Provider"]:::state
        WRProvider["WebRunnerProvider"]:::state
        Stores["Stores (src/stores/)"]:::state
        Reducers["Reducers (src/reducers/)"]:::state
    end

    subgraph "Host-WebView Boundary"
        direction TB
        MessageBus["Message Bus (src/messaging/index.ts)"]:::message
    end

    subgraph "WebRunner Layer"
        direction TB
        WRHost["WebRunner Host Component"]:::runner
        Bundles["Web.bundle (html/Web.bundle/)"]:::runner
        WebView["Hidden WebView"]:::runner
        Polkadot["@polkadot JS + WASM"]:::runner
    end

    subgraph "External & Native Services"
        direction TB
        RPC["RPC Endpoints"]:::external
        Banxa["Banxa Config"]:::external
        Coinbase["Coinbase Config"]:::external
        Transak["Transak Config"]:::external
        StorageUtil["Secure Storage (src/utils/storage.ts)"]:::external
        NetworkUtil["Network Utils (src/utils/network.ts)"]:::external
        Deeplink["DeepLink Utils (src/utils/deeplink/index.ts)"]:::external
        QRModule["Camera/QR Modules"]:::external
        MinimizerA["RCTMinimizer Android"]:::external
        MinimizerI["RCTMinimizer iOS"]:::external
        StaticServer["StaticServer Bridge"]:::external
    end

    %% Connections
    Root -->|boots| App
    App -->|uses| Navigator
    App -->|renders| Screens
    App -->|renders| Components

    App -->|wraps| ModalCtx
    App -->|wraps| TxCtx
    App -->|wraps| WRProvider
    ModalCtx -->|provides| Stores
    TxCtx -->|provides| Stores
    WRProvider -->|provides| Stores

    Stores -->|managed by| Reducers

    WRProvider -->|posts/receives| MessageBus
    MessageBus -.->|JSON-RPC| WebView
    WebView -->|loads| Bundles
    WebView -->|executes| Polkadot
    WebView -->|calls| RPC
    WebView -->|calls| Polkadot
    RPC -.->|data| Polkadot
    Polkadot -->|response| WebView
    WebView -.->|message| MessageBus
    MessageBus -->|updates| Stores
    Stores -->|renders| Components

    App -->|calls| StorageUtil
    App -->|calls| NetworkUtil
    App -->|calls| Deeplink
    App -->|calls| QRModule
    App -->|calls| MinimizerA
    App -->|calls| MinimizerI
    App -->|calls| StaticServer
    App -->|uses| Banxa & Coinbase & Transak

    %% Click Events
    click Screens "https://github.com/koniverse/subwallet-mobile/tree/master/src/screens/"
    click Components "https://github.com/koniverse/subwallet-mobile/tree/master/src/components/"
    click Navigator "https://github.com/koniverse/subwallet-mobile/blob/master/src/AppNavigator.tsx"
    click ModalCtx "https://github.com/koniverse/subwallet-mobile/blob/master/src/providers/AppModalContext.tsx"
    click TxCtx "https://github.com/koniverse/subwallet-mobile/blob/master/src/providers/TransactionContext.tsx"
    click WRProvider "https://github.com/koniverse/subwallet-mobile/blob/master/src/providers/WebRunnerProvider/WebRunnerProvider.tsx"
    click Stores "https://github.com/koniverse/subwallet-mobile/tree/master/src/stores/"
    click Reducers "https://github.com/koniverse/subwallet-mobile/tree/master/src/reducers/"
    click MessageBus "https://github.com/koniverse/subwallet-mobile/blob/master/src/messaging/index.ts"
    click Bundles "https://github.com/koniverse/subwallet-mobile/tree/master/html/Web.bundle/"
    click WRHost "https://github.com/koniverse/subwallet-mobile/blob/master/src/providers/WebRunnerProvider/WebRunner.tsx"
    click MinimizerA "https://github.com/koniverse/subwallet-mobile/blob/master/android/app/src/main/java/app/subwallet/mobile/nativeModules/RCTMinimizer.java"
    click MinimizerI "https://github.com/koniverse/subwallet-mobile/blob/master/ios/SubWalletMobile/NativeModules/RCTMinimizer/RCTMinimizer.m"
    click StaticServer "https://github.com/koniverse/subwallet-mobile/blob/master/src/components/common/ReactNativeStaticServer/index.ts"
    click StorageUtil "https://github.com/koniverse/subwallet-mobile/blob/master/src/utils/storage.ts"
    click Banxa "https://github.com/koniverse/subwallet-mobile/blob/master/src/constants/buy/banxa.ts"
    click Coinbase "https://github.com/koniverse/subwallet-mobile/blob/master/src/constants/buy/coinbase.ts"
    click Transak "https://github.com/koniverse/subwallet-mobile/blob/master/src/constants/buy/transak.ts"
    click NetworkUtil "https://github.com/koniverse/subwallet-mobile/blob/master/src/utils/network.ts"
    click Deeplink "https://github.com/koniverse/subwallet-mobile/blob/master/src/utils/deeplink/index.ts"
    click CryptoReady "https://github.com/koniverse/subwallet-mobile/blob/master/src/hooks/init/useCryptoReady.ts"
    click FetchChain "https://github.com/koniverse/subwallet-mobile/blob/master/src/hooks/common/useFetchChainInfo.ts"
    click Root "https://github.com/koniverse/subwallet-mobile/blob/master/src/Root.tsx"
    click App "https://github.com/koniverse/subwallet-mobile/blob/master/src/App.tsx"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#0288D1
    classDef state fill:#E8F5E9,stroke:#388E3C
    classDef message fill:#FFF3E0,stroke:#F57C00,stroke-dasharray: 5 5
    classDef runner fill:#FFE0B2,stroke:#F57C00
    classDef external fill:#CFD8DC,stroke:#607D8B
```
