# ethereum/kohaku-extension architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/kohaku-extension
- Repository: https://github.com/ethereum/kohaku-extension

## Overview

##### Project type and purpose
- This is a full-stack, multi-platform Web3 wallet with these outputs:
- Browser extensions (Chrome/WebKit, Gecko, Safari)
- Web applications (Ambire Wallet web, Benzin explorer, Legends rewards)
- Mobile apps (Android, iOS via React Native bare + Expo modules)
- It integrates on-chain wallet functionality (EIP-1193 provider), hardware wallets (Ledger, Trezor, Lattice), an ERC-4337 transaction explorer (Benzin), and a gamified rewards portal (Legends).

##### High-level components
a. UI layers (React/React Native/React Native Web)
– Mobile app (Android/iOS, Expo + native modules)
– Web wallet UI (React Native Web / webpack)
– Browser extension popup UI (React Native Web)
– Benzin explorer (Standalone React web)
– Legends rewards portal (Standalone React web)
b. Shared core
– ambire-common submodule: shared React components, hooks, contexts, services, utilities, theming
c. State & controller layer
– Web extension controllers (background script, message buses, provider)
– React contexts & hooks (account, networks, theme, toast, storage, etc.)
d. Native modules & hardware wallets
– Android native host, JSI / TurboModules, Flipper integration
– iOS AppDelegate, native modules
– Hardware-wallet libs and controllers (Ledger/Trezor/Lattice)
e. External interactions
– Ethereum JSON-RPC nodes / relayer services
– Ethers.js / custom fetch service
– Hardware-wallet connectors via USB/BLE
– Browser storage (IndexedDB, chrome.storage)
– Analytics / CrashReporting
f. Build & deployment
– Metro bundler (mobile)
– Webpack (web, extensions)
– Buck / Gradle (Android)
– Xcode projects (iOS / Safari extension)
– CI workflows (GitHub Actions)

##### Relationships & data flows
- UI triggers React Context → dispatches actions to controller hooks → controller calls services (fetch, hardware) → updates state → UI re-renders
- Browser popup ↔ background script via port messages (messenger modules) to handle signing, network requests, storage
- In-page injection: content script injects provider into DApp, calls background via RPC flow
- Mobile UI ↔ native modules via TurboModule / JSI layer (new architecture registry in android/app/src/main/jni)
- Shared core modules imported by all UIs for consistency

##### Architectural patterns & principles
– Modular layers: UI / contexts/hooks / services / native connectors
– Dependency injection via React Contexts
– Message-bus pattern for extension background ↔ popup ↔ in-page
– Shared monorepo submodule (ambire-common) for cross-platform code reuse
– Separation between “presentation” (React components) and “business logic” (services, controllers)
– Build-time configuration via env files, Metro/webpack configs

- Full-stack wallet (browser + web):
– Show shared core imported by both UI and background
– Label hardware wallet connectors as external services
- Mobile app:
– Show Expo modules as plug-ins
– Show external RPC calls to Ethereum node
- Benzin & Legends:

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "UI Layers"
    UI_Mobile["Mobile App UI"]:::ui
    UI_WebWallet["Web Wallet UI"]:::ui
    UI_ExtPopup["Extension Popup UI"]:::ui
    UI_Benzin["Benzin Explorer"]:::ui
    UI_Legends["Legends Portal"]:::ui
  end

  subgraph "Shared Core"
    Core["ambire-common"]:::core
  end

  subgraph "State & Controllers"
    Ctx["React Contexts & Hooks"]:::state
    ExtBG["Extension Background Service"]:::state
  end

  subgraph "Services & Controllers"
    Srv["Fetch & Ethers.js Services"]:::service
    HWCtrl["Hardware Wallet Controllers"]:::service
  end

  subgraph "Native Modules & Hardware"
    AndroidRN["Android Host & JSI"]:::native
    iOSNM["iOS AppDelegate & Expo"]:::native
    HWLib["Hardware Wallet Libs"]:::native
  end

  subgraph "External Systems"
    RPC["Ethereum JSON-RPC Nodes"]:::external
    Storage["Browser Storage"]:::external
    Analytics["Analytics/CrashReporting"]:::external
  end

  %% Relationships
  UI_Mobile -->|triggers| Ctx
  UI_WebWallet -->|triggers| Ctx
  UI_ExtPopup -->|messages| ExtBG
  UI_Benzin -->|triggers| Ctx
  UI_Legends -->|triggers| Ctx

  Core --> UI_Mobile
  Core --> UI_WebWallet
  Core --> UI_ExtPopup
  Core --> UI_Benzin
  Core --> UI_Legends
  Core --> Ctx
  Core --> ExtBG

  Ctx -->|calls| Srv
  ExtBG -->|calls| Srv
  Srv -->|fetch| RPC
  Srv -->|connect| HWLib

  UI_Mobile -->|native calls| AndroidRN
  UI_Mobile -->|native calls| iOSNM
  AndroidRN -->|uses| HWLib
  iOSNM -->|uses| HWLib

  HWCtrl -->|controls| HWLib
  Srv -->|storage| Storage
  Srv -->|reporting| Analytics

  %% Click Events
  click UI_Mobile "https://github.com/ethereum/kohaku-extension/blob/main/App.tsx"
  click UI_Mobile "https://github.com/ethereum/kohaku-extension/blob/main/App.web.tsx"
  click AndroidRN "https://github.com/ethereum/kohaku-extension/blob/main/android/app/src/main/java/com/ambire/newarchitecture/MainApplicationReactNativeHost.java"
  click AndroidRN "https://github.com/ethereum/kohaku-extension/blob/main/android/app/src/main/java/com/ambire/newarchitecture/components/MainComponentsRegistry.java"
  click AndroidRN "https://github.com/ethereum/kohaku-extension/blob/main/android/app/src/main/java/com/ambire/newarchitecture/modules/MainApplicationTurboModuleManagerDelegate.java"
  click iOSNM "https://github.com/ethereum/kohaku-extension/blob/main/ios/ambire/AppDelegate.mm"
  click iOSNM "https://github.com/ethereum/kohaku-extension/blob/main/ios/ambire/Supporting/Expo.plist"
  click Core "https://github.com/ethereum/kohaku-extension/tree/main/src/ambire-common"
  click UI_WebWallet "https://github.com/ethereum/kohaku-extension/blob/main/src/index.js"
  click UI_WebWallet "https://github.com/ethereum/kohaku-extension/blob/main/shim.web.js"
  click UI_WebWallet "https://github.com/ethereum/kohaku-extension/blob/main/webpack.config.js"
  click UI_WebWallet "https://github.com/ethereum/kohaku-extension/tree/main/src/web/components"
  click UI_WebWallet "https://github.com/ethereum/kohaku-extension/tree/main/src/web/modules"
  click ExtBG "https://github.com/ethereum/kohaku-extension/blob/main/src/web/extension-services/background/background.ts"
  click ExtBG "https://github.com/ethereum/kohaku-extension/tree/main/src/web/extension-services/background/controllers"
  click ExtBG "https://github.com/ethereum/kohaku-extension/blob/main/src/web/extension-services/background/provider/ProviderController.ts"
  click ExtBG "https://github.com/ethereum/kohaku-extension/blob/main/src/web/extension-services/background/provider/rpcFlow.ts"
  click ExtBG "https://github.com/ethereum/kohaku-extension/blob/main/src/web/extension-services/background/provider/handleProviderRequests.ts"
  click ExtBG "https://github.com/ethereum/kohaku-extension/blob/main/src/web/public/manifest.json"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/common/contexts"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/common/hooks"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/web/contexts"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/web/hooks"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/benzin/context"
  click Ctx "https://github.com/ethereum/kohaku-extension/tree/main/src/benzin/hooks"
  click UI_Benzin "https://github.com/ethereum/kohaku-extension/blob/main/src/benzin/index.js"
  click UI_Benzin "https://github.com/ethereum/kohaku-extension/blob/main/src/benzin/public/index.html"
  click UI_Benzin "https://github.com/ethereum/kohaku-extension/blob/main/src/benzin/BenzinInit.tsx"
  click UI_Benzin "https://github.com/ethereum/kohaku-extension/tree/main/src/benzin/screens"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/blob/main/src/legends/index.js"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/blob/main/src/legends/LegendsInit.tsx"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/tree/main/src/legends/common"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/tree/main/src/legends/components"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/tree/main/src/legends/modules"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/tree/main/src/legends/contexts"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/tree/main/src/legends/hooks"
  click UI_Legends "https://github.com/ethereum/kohaku-extension/blob/main/src/legends/public/index.html"
  click HWCtrl "https://github.com/ethereum/kohaku-extension/tree/main/src/web/modules/hardware-wallet/controllers"
  click HWCtrl "https://github.com/ethereum/kohaku-extension/tree/main/src/web/modules/hardware-wallet/hooks"
  click HWCtrl "https://github.com/ethereum/kohaku-extension/tree/main/src/web/modules/hardware-wallet/libs"
  click HWCtrl "https://github.com/ethereum/kohaku-extension/blob/main/src/common/services/device/device.ts"
  click Srv "https://github.com/ethereum/kohaku-extension/blob/main/src/common/services/fetch/fetch.ts"
  click Srv "https://github.com/ethereum/kohaku-extension/tree/main/src/web/extension-services/background/provider"

  %% Styles
  classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
  classDef core fill:#90ee90,stroke:#333,stroke-width:1px
  classDef state fill:#98fb98,stroke:#333,stroke-width:1px
  classDef service fill:#ffffe0,stroke:#333,stroke-width:1px
  classDef native fill:#d3d3d3,stroke:#333,stroke-width:1px
  classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
