# metamask/metamask-extension architecture

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

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

## Overview

- UI → Background Process
- Content Script → Background Process
- Background Process → Controllers
- Inter-controller Communications

- Extension → Ethereum Networks
- Extension → Hardware Wallets
- Extension → Web3 Sites
- Extension → API Services

a. Security & Privacy
- LavaMoat Security Layer
- Encryption Systems
- Permission Management
- Phishing Detection

b. Transaction Management
- Gas Fee Estimation
- Transaction Queue
- Signature Management
- Network Switching

c. Account Management
- Wallet Creation/Import
- Account Recovery
- Address Book
- Token Management

##### Architecture Specifics

a. Extension Architecture
- Popup UI (React/Redux)
- Background Service
- Content Scripts
- Injected Provider

b. State Management
- Redux Store
- Background State
- Persistence Layer
- State Synchronization

##### Integration Points

Connection points for:
- Dapp Interactions
- RPC Endpoints
- Hardware Wallets
- External Services

##### Security Boundaries

- Trusted Extension Context
- Untrusted Webpage Context
- Secure Storage Areas
- External Communication Boundaries

- UI Layer (React/Redux)
- Extension Architecture (Background/Content Scripts)
- Core Controllers
- External Integrations

##### Clear distinction between
- User-facing components
- Background processes
- Security boundaries
- External communications

##### Security features
- LavaMoat protection
- Encryption systems
- Permission management
- Phishing protection

##### Important flows
- Transaction processing
- Account management
- Network switching
- State synchronization

- Nested components
- Clear labeling
- Grouping of related components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef ui fill:#a8d1f0,stroke:#333
    classDef extension fill:#90EE90,stroke:#333
    classDef core fill:#FFE5B4,stroke:#333
    classDef external fill:#DDA0DD,stroke:#333
    classDef security fill:#FFB6C1,stroke:#333
    classDef confirm fill:#FFA07A,stroke:#333

    %% User Interface Layer
    subgraph UI[User Interface Layer]
        MMUI[MetaMask UI]
        PopupUI[Popup Interface]
        NotifSys[Notification System]
        Settings[Settings Pages]
        AccMgmt[Account Management]
        
        %% Confirmation Screens
        subgraph CONF[Confirmation Screens]
            TxConf[Transaction Confirmation]
            MsgConf[Message Signature]
            TypedMsgConf[Typed Message Signature]
            PersonalMsgConf[Personal Message Signature]
            AddTokenConf[Add Token Confirmation]
            ConnectConf[Connect Site Confirmation]
            AddNetConf[Add Network Confirmation]
            SwitchNetConf[Switch Network Confirmation]
        end
    end

    %% Extension Layer
    subgraph EXT[Extension Layer]
        BgScripts[Background Scripts]
        ContScripts[Content Scripts]
        InjScripts[Injection Scripts]
        ServWork[Service Workers]
    end

    %% Core Services Layer
    subgraph CORE[Core Services Layer]
        Controller[Controller System]
        KeyringCtrl[KeyringController]
        NetworkCtrl[NetworkController]
        TxCtrl[TransactionController]
        PermCtrl[PermissionController]
        SecProvCtrl[SecurityProviderController]
    end

    %% Security & Privacy
    subgraph SEC[Security & Privacy]
        LavaMoat[LavaMoat Security Layer]
        Encryption[Encryption Systems]
        PermMgmt[Permission Management]
        PhishDet[Phishing Detection]
    end

    %% External Integrations
    subgraph EXT_INT[External Integrations]
        EthNet[Ethereum Networks]
        Web3Prov[Web3 Provider]
        HWWallet[Hardware Wallets]
        BlockAPI[Blockchain APIs]
        IPFS[IPFS Gateway]
    end

    %% Relationships
    UI --> BgScripts
    ContScripts --> BgScripts
    BgScripts --> Controller
    Controller --> |Manages| KeyringCtrl & NetworkCtrl & TxCtrl & PermCtrl & SecProvCtrl
    Controller -.-> EXT_INT
    SEC --> Controller

    %% Confirmation Flow Relationships
    TxCtrl --> TxConf
    KeyringCtrl --> MsgConf & TypedMsgConf & PersonalMsgConf
    NetworkCtrl --> AddNetConf & SwitchNetConf
    PermCtrl --> ConnectConf
    Controller --> AddTokenConf

    %% Click Events
    click MMUI "https://github.com/metamask/metamask-extension/tree/main/ui/components/"
    click PopupUI "https://github.com/metamask/metamask-extension/blob/main/app/popup.html"
    click NotifSys "https://github.com/metamask/metamask-extension/tree/main/ui/components/app/notifications/"
    click Settings "https://github.com/metamask/metamask-extension/tree/main/ui/pages/settings/"
    click AccMgmt "https://github.com/metamask/metamask-extension/tree/main/ui/pages/accounts/"
    click BgScripts "https://github.com/metamask/metamask-extension/blob/main/app/scripts/background.js"
    click ContScripts "https://github.com/metamask/metamask-extension/blob/main/app/scripts/contentscript.js"
    click InjScripts "https://github.com/metamask/metamask-extension/blob/main/app/scripts/inpage.js"
    click ServWork "https://github.com/metamask/metamask-extension/blob/main/app/scripts/runtime-cjs.ts"
    click Controller "https://github.com/metamask/metamask-extension/blob/main/app/scripts/metamask-controller.js"
    click KeyringCtrl "https://github.com/metamask/metamask-extension/blob/main/app/scripts/controllers/keyring-controller.ts"
    click NetworkCtrl "https://github.com/metamask/metamask-extension/blob/main/app/scripts/controllers/network-controller.ts"
    click TxCtrl "https://github.com/metamask/metamask-extension/tree/main/app/scripts/controllers/transactions/"
    click PermCtrl "https://github.com/metamask/metamask-extension/tree/main/app/scripts/controllers/permissions/"
    click SecProvCtrl "https://github.com/metamask/metamask-extension/tree/main/app/scripts/controllers/security-provider/"
    click HWWallet "https://github.com/metamask/metamask-extension/blob/main/app/scripts/controllers/permissions/specifications.js"
    click Web3Prov "https://github.com/metamask/metamask-extension/blob/main/app/scripts/lib/provider-injection.js"
    click IPFS "https://github.com/metamask/metamask-extension/tree/main/app/scripts/lib/ipfs-gateway/"
    click BlockAPI "https://github.com/metamask/metamask-extension/tree/main/app/scripts/controllers/network/"
    click LavaMoat "https://github.com/metamask/metamask-extension/tree/main/lavamoat/"
    click PhishDet "https://github.com/metamask/metamask-extension/tree/main/app/scripts/lib/phishing-controller/"
    click PermMgmt "https://github.com/metamask/metamask-extension/tree/main/app/scripts/controllers/permissions/"

    %% Apply classes
    class MMUI,PopupUI,NotifSys,Settings,AccMgmt ui
    class BgScripts,ContScripts,InjScripts,ServWork extension
    class Controller,KeyringCtrl,NetworkCtrl,TxCtrl,PermCtrl,SecProvCtrl core
    class EthNet,Web3Prov,HWWallet,BlockAPI,IPFS external
    class LavaMoat,Encryption,PermMgmt,PhishDet security
    class TxConf,MsgConf,TypedMsgConf,PersonalMsgConf,AddTokenConf,ConnectConf,AddNetConf,SwitchNetConf confirm
```
