# mavryk-network/mavryk-wallet architecture

> Architecture diagram of the GitHub repository mavryk-network/mavryk-wallet, 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/mavryk-network/mavryk-wallet
- Repository: https://github.com/mavryk-network/mavryk-wallet

## Overview

This project is a browser extension for a cryptocurrency wallet—specifically for the Mavryk blockchain. Its primary purpose is to allow users to manage tokens, NFTs, and interface with decentralized applications (dApps) directly in their web browser. The project is built largely as a full-stack client-side application, with a rich React-based UI, a Redux (or similar) state management layer, extensive API integrations, and supporting libraries for blockchain communication, internationalization, and testing.

##### Major Components
- User Interface (UI) Layer – Represented by the “src/app” directory. This includes pages, atoms, molecules, and templates (e.g., various React components for wallet pages, modals, on-boarding, transactions, and notifications).
- State Management – The “src/store” directory contains Redux reducers, actions, epics, and selectors which manage the application state.
- Business Logic & API Integration – The “src/lib/apis” folder (and other related “src/lib” subdirectories) encapsulate logic for accessing blockchain API endpoints (for Mavryk, NFT management, dApps, and more), handling analytics, intercom, notifications, and even handling internationalization.
- Background and Content Scripts – Files such as “src/background.ts”, “src/content-scripts”, “src/popup.tsx”, “src/fullpage.tsx”, and “src/replaceAds.ts” indicate how the extension interacts with the browser context and injects content or provides background processing.
- Internationalization (i18n) Support – With dedicated scripts in “bin/i18n-*.js”, “src/lib/i18n”, and localized files under “public/_locales”, the project supports multiple languages.
- Testing and E2E – The “e2e” directory holds extensive end-to-end test scenarios (using feature files, page objects, step definitions, etc.) that validate the wallet’s functionality.
- Build and Configuration – Webpack configuration files (in “webpack”) and other config files (like “.babelrc”, “tsconfig.json”) are used to build and bundle the extension code for various browsers.
- Native & Platform-Specific Code – The “xcode” directory shows that there is a platform-specific component (likely for Safari or mobile integration) that integrates the extension via native wrappers.

##### Relationships and Interactions
- The UI components send user interactions to the state management layer (Redux store) which mediates data flow.
- State changes trigger business logic side-effects (using epics or hooks) that then invoke API calls in the “src/lib/apis” layer.
- API integrations communicate with external services (e.g., Mavryk blockchain nodes, NFT services, exchange rate providers, etc.) in order to fetch or post data.
- The background script and content scripts manage browser-specific integration and messaging between the web page and the extension’s UI.
- The build system (Webpack) compiles and bundles all of the above components, while the i18n modules and localization assets ensure multi-language support.
- Testing (e2e scripts) covers user flows and guarantees that interactions between the UI, store, and APIs work as expected.

##### Architectural Patterns & Design Principles
- Component-Based Architecture: The React-based UI is organized into reusable atoms, molecules, and templates.
- Separation of Concerns: The code is organized into distinct layers – UI, state management, business logic, and external integrations.
- Modularization: Library functions and utilities are isolated in “src/lib” (for analytics, ledger handling, notifications, etc.) so they can be unit-tested and reused throughout the application.
- Extensibility: The project includes modular handling for internationalization, testing, and deployment to multiple browsers (Chrome, Firefox, Opera).
- Messaging & Asynchronous Data Flow: Use of Redux epics or similar side-effect models for API integrations and background tasks.

##### Relevant Technologies and Frameworks
- React and React hooks for UI components.
- Redux (or a similar state management tool) for state handling.
- Webpack, Babel for building and bundling.
- TypeScript for typed development.
- E2E testing frameworks (likely Cucumber or a similar tool as indicated by “e2e/src/features”).
- APIs for blockchain interactions and external service integrations within “src/lib/apis”.
- i18n support using JSON files and helper libraries.
- Xcode-based native integration (for Safari or iOS environments) as seen in the “xcode” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client-Side Layers
    subgraph "Client-Side Layers"
        UI["UI Layer\n(React Components)"]:::ui
        State["State Management\n(Redux Store)"]:::state
        API["Business Logic & API Integration\n(Blockchain APIs, NFT, Analytics)"]:::api
    end

    UI -->|"dispatches"| State
    State -->|"triggers"| API
    API -->|"requests"| External["External Blockchain & dApp Services"]:::external
    External -->|"responds"| API
    API -->|"updates"| State
    State -->|"renders"| UI

    %% Extension Scripts
    subgraph "Extension Scripts"
        BG["Background\n(src/background.ts)"]:::scripts
        CS["Content Scripts\n(src/content-scripts)"]:::scripts
        Popup["Popup\n(src/popup.tsx)"]:::scripts
        Fullpage["Fullpage\n(src/fullpage.tsx)"]:::scripts
        ReplaceAds["ReplaceAds\n(src/replaceAds.ts)"]:::scripts
    end

    UI -->|"communicates"| BG
    BG -->|"sendsMessages"| UI

    %% Internationalization Support
    subgraph "Internationalization"
        I18nBin["i18n Bin\n(bin/i18n-*)"]:::i18n
        I18nLib["i18n Lib\n(src/lib/i18n)"]:::i18n
        I18nLocales["Locale Assets\n(public/_locales)"]:::i18n
    end

    I18nLib -->|"supports"| UI

    %% Build & Configuration
    subgraph "Build & Configuration"
        Webpack["Webpack\n(webpack)"]:::build
        Babel["Babel Config\n(.babelrc)"]:::build
        TSConfig["TSConfig\n(tsconfig.json)"]:::build
    end

    Webpack -->|"bundles"| UI
    Babel -->|"transpiles"| UI
    TSConfig -->|"configures"| UI

    %% Testing Suite
    subgraph "Testing Suite"
        Test["E2E Tests\n(e2e)"]:::test
    end

    Test -->|"validates"| UI
    Test -->|"validates"| API

    %% Native Integration
    subgraph "Native Integration"
        Native["Xcode Project\n(xcode)"]:::native
    end

    Webpack -->|"packages"| Native

    %% Click Events
    click UI "https://github.com/mavryk-network/mavryk-wallet/tree/development/src/app"
    click State "https://github.com/mavryk-network/mavryk-wallet/tree/development/src/store"
    click API "https://github.com/mavryk-network/mavryk-wallet/tree/development/src/lib/apis"
    click BG "https://github.com/mavryk-network/mavryk-wallet/blob/development/src/background.ts"
    click CS "https://github.com/mavryk-network/mavryk-wallet/tree/development/src/content-scripts"
    click Popup "https://github.com/mavryk-network/mavryk-wallet/blob/development/src/popup.tsx"
    click Fullpage "https://github.com/mavryk-network/mavryk-wallet/blob/development/src/fullpage.tsx"
    click ReplaceAds "https://github.com/mavryk-network/mavryk-wallet/blob/development/src/replaceAds.ts"
    click I18nBin "https://github.com/mavryk-network/mavryk-wallet/tree/development/bin"
    click I18nLib "https://github.com/mavryk-network/mavryk-wallet/tree/development/src/lib/i18n"
    click I18nLocales "https://github.com/mavryk-network/mavryk-wallet/tree/development/public/_locales"
    click Test "https://github.com/mavryk-network/mavryk-wallet/tree/development/e2e"
    click Webpack "https://github.com/mavryk-network/mavryk-wallet/tree/development/webpack"
    click Babel "https://github.com/mavryk-network/mavryk-wallet/blob/development/.babelrc"
    click TSConfig "https://github.com/mavryk-network/mavryk-wallet/blob/development/tsconfig.json"
    click Native "https://github.com/mavryk-network/mavryk-wallet/tree/development/xcode"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef state fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef api fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef scripts fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef i18n fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef build fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef test fill:#d6d8db,stroke:#333,stroke-width:2px;
    classDef native fill:#e2d6f7,stroke:#333,stroke-width:2px;
    classDef external fill:#ffeeba,stroke:#333,stroke-width:2px;
```
