# rainbow-me/rainbow architecture

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

- Interactive diagram: https://gitdiagram.com/rainbow-me/rainbow
- Repository: https://github.com/rainbow-me/rainbow

## Overview

##### Main Components
a. User Interface (UI) Layer:
- The core visual layer is implemented in React Native. It is divided into multiple sections such as “screens” (for different wallet functionalities like Send, Swap, Settings, etc.), “components” (reusable UI elements), and a dedicated “design-system” module that holds all themed styles, layout components, typography, and reusable primitives.
b. Business Logic and State Management Layer:
- There is robust state management with folders like “src/state”, “src/redux”, and also hooks in “src/hooks”. This layer handles wallet data, transaction states, pending operations, user preferences, and synchronizes with external blockchain data.
c. Native and Platform-specific Integration:
- The project contains separate directories for Android and iOS which house native code, build scripts, CocoaPods files, and additional configurations for wallet-specific native modules. Additionally, a browser extension exists with assets in “src/browser” and “src/browserMessaging”.
d. Network, API, and External Services Layer:
- This includes modules interfacing with Ethereum networks (using Infura, Etherscan, ETH Gas Station), GraphQL queries in “src/graphql”, WalletConnect integrations in “src/walletConnect”, and asset fetching (using Imgix for images).
e. Utilities and Helpers:
- These are spread across “src/helpers”, “src/utils”, “src/raps”, and others. They contain functions to build transactions, format dates and numbers, manage encryption and keychain access, and handle third‐party API responses.
f. Persistence and Migration:
- Storage modules in “src/storage” and “src/migrations” take care of local persistence (such as MMKV and legacy migrations) ensuring user wallet data and settings persist between sessions.
g. Analytics & Performance:
- The application tracks performance (e.g., via “src/performance”) and user events (in “src/analytics”) to feed data to backend analytics and Sentry error tracking.
h. External Dependencies & Environment Configuration:
- Configuration files such as .env.example, yarn scripts, and platform-specific configuration files integrate external services (Firebase, Google services, etc.) and environment keys.

##### Component Interactions
- Native modules in the “android” and “ios” directories expose integrations for device-specific functionalities (camera access, fingerprint/faceID, secure storage, etc.).
- Persistence modules and migration routines ensure that state changes are saved locally and are up-to-date on subsequent launches.

##### Architectural Patterns & Design Principles
- Separation of concerns is applied vigorously: UI components are decoupled from business logic; state management and hooks abstract away data manipulation and API calls.
- The design-system enables reusable and themed components ensuring consistency across the multi-platform UI.
- Modularization is reflected through discrete folders (e.g., “src/components”, “src/hooks”, “src/state”) – each with a well-defined responsibility.
- Use of dependency injection and contexts (as seen in “src/helpers/RainbowContext.tsx” and “src/design-system/context”) fosters loose coupling and testability.
- Emphasis is placed on performance: state synchronization, reanimated worklets, and memoized hooks help maintain responsive interactions on mobile devices.

##### Relevant Technologies & Frameworks
- React Native for mobile UI with platform-specific native code.
- Yarn for dependency management, with scripts that set up bundles and pods.
- Node.js 16 (with NVM) as the development runtime.
- State management approaches with Redux, Recoil, and React Query.
- GraphQL for querying blockchain-related data.
- External APIs: Infura, Etherscan, Imgix, Firebase.
- Tools like Watchman, CocoaPods, and Xcode are used in native building pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entity
    User("User"):::external

    %% UI Layer
    subgraph "UI Layer"
        UIScreens("Screens (React Native)"):::ui
        UIComponents("Reusable UI Components"):::ui
        DesignSystem("Design System & Theming"):::ui
    end

    %% Business Logic & State Management
    subgraph "Business Logic & State Management"
        CustomHooks("Custom Hooks"):::business
        State("State"):::business
        Redux("Redux"):::business
        CombinedState("Combined Global State"):::business
    end

    %% Native & Platform-specific Integration
    subgraph "Native & Platform-specific Integration"
        Android("Android Native Modules"):::native
        iOS("iOS Native Modules"):::native
        BrowserExtension("Browser Extension Assets"):::native
        BrowserMessaging("Browser Messaging"):::native
    end

    %% Network, API & External Services
    subgraph "Network/API Integration"
        GraphQL("GraphQL Integration"):::network
        WalletConnect("WalletConnect Integration"):::network
    end

    %% Persistence & Migration
    subgraph "Persistence & Migration"
        Storage("Local Storage"):::persistence
        Migrations("Database Migrations"):::persistence
    end

    %% Analytics & Performance
    subgraph "Analytics & Performance"
        AnalyticsEvents("Analytics Events"):::analytics
        Performance("Performance Monitoring"):::analytics
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        Helpers("Helper Functions"):::utilities
        Utils("Utility Modules"):::utilities
        DAppLogic("dApp Related Logic"):::utilities
    end

    %% External Dependencies & Configuration
    subgraph "External Dependencies"
        EnvConfig("Environment & External Config"):::external
    end

    %% Connections
    User -->|"initiates"| UIScreens
    UIScreens -->|"triggers"| CustomHooks
    UIComponents -->|"enhances"| CustomHooks
    DesignSystem -->|"supports"| UIComponents

    CustomHooks -->|"dispatches"| State
    CustomHooks -->|"dispatches"| Redux
    State -->|"merges into"| CombinedState
    Redux -->|"merges into"| CombinedState

    CombinedState -->|"updates"| UIScreens

    CombinedState -->|"requests"| GraphQL
    CombinedState -->|"requests"| WalletConnect
    GraphQL -->|"responds to"| CombinedState
    WalletConnect -->|"responds to"| CombinedState

    CombinedState -->|"persists"| Storage
    Migrations -->|"updates"| Storage

    CombinedState -->|"logs"| AnalyticsEvents
    AnalyticsEvents -->|"monitors"| Performance

    EnvConfig -->|"configures"| CombinedState

    CustomHooks -->|"utilizes"| Helpers
    CustomHooks -->|"utilizes"| Utils
    CustomHooks -->|"utilizes"| DAppLogic

    CustomHooks -->|"calls"| Android
    CustomHooks -->|"calls"| iOS

    User -->|"uses"| BrowserExtension
    BrowserExtension -->|"communicates"| BrowserMessaging

    %% Click Events
    click UIScreens "https://github.com/rainbow-me/rainbow/tree/develop/src/screens"
    click UIComponents "https://github.com/rainbow-me/rainbow/tree/develop/src/components"
    click DesignSystem "https://github.com/rainbow-me/rainbow/tree/develop/src/design-system"

    click CustomHooks "https://github.com/rainbow-me/rainbow/tree/develop/src/hooks"
    click State "https://github.com/rainbow-me/rainbow/tree/develop/src/state"
    click Redux "https://github.com/rainbow-me/rainbow/tree/develop/src/redux"

    click Android "https://github.com/rainbow-me/rainbow/tree/develop/android"
    click iOS "https://github.com/rainbow-me/rainbow/tree/develop/ios"
    click BrowserExtension "https://github.com/rainbow-me/rainbow/tree/develop/src/browser"
    click BrowserMessaging "https://github.com/rainbow-me/rainbow/tree/develop/src/browserMessaging"

    click GraphQL "https://github.com/rainbow-me/rainbow/tree/develop/src/graphql"
    click WalletConnect "https://github.com/rainbow-me/rainbow/tree/develop/src/walletConnect"

    click Storage "https://github.com/rainbow-me/rainbow/tree/develop/src/storage"
    click Migrations "https://github.com/rainbow-me/rainbow/tree/develop/src/migrations"

    click AnalyticsEvents "https://github.com/rainbow-me/rainbow/tree/develop/src/analytics"
    click Performance "https://github.com/rainbow-me/rainbow/tree/develop/src/performance"

    click Helpers "https://github.com/rainbow-me/rainbow/tree/develop/src/helpers"
    click Utils "https://github.com/rainbow-me/rainbow/tree/develop/src/utils"
    click DAppLogic "https://github.com/rainbow-me/rainbow/tree/develop/src/raps"

    click EnvConfig "https://github.com/rainbow-me/rainbow/blob/develop/.env.example"

    %% Styles
    classDef ui fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef business fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef native fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef network fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef persistence fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef analytics fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
    classDef utilities fill:#E0F7FA,stroke:#00838F,stroke-width:2px;
    classDef external fill:#F1F8E9,stroke:#7CB342,stroke-width:2px;
```
