# offchainlabs/arbitrum-token-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/offchainlabs/arbitrum-token-bridge
- Repository: https://github.com/offchainlabs/arbitrum-token-bridge

## Overview

##### Project type and purpose
- This is a monorepo for the Arbitrum Token Bridge, a full-stack web application built with Next.js (React) that provides a UI for bridging tokens between Ethereum L1, Arbitrum L2, and Orbit chains.
- It also contains auxiliary CLI scripts (under packages/scripts) to manage chain configurations and a token-bridge SDK (under arb-token-bridge-ui/src/token-bridge-sdk) to orchestrate on-chain transactions.

##### File structure
- Top-level:
- Monorepo root with CI/CD config (.github/workflows, vercel.json), lint/format configs, workspace definitions (package.json, tsconfig.base.json).
- packages/arb-token-bridge-ui: the Next.js app (UI + serverless API)
- packages/scripts: standalone Node.js CLI tools
- Under arb-token-bridge-ui:
- src/pages – React pages (including pages/api/** for Next.js serverless endpoints)
- src/components, src/hooks, src/util, src/token-bridge-sdk – feature modules (UI, business logic, SDK)
- public – static assets
- tests/e2e – Cypress/Synpress end-to-end tests
- scripts – build-time data-generation scripts
- Presence of Next.js API routes indicates a serverless backend layer co-located with the UI.

##### README for additional insights
- Confirms a dev workflow: run Node/NVM, yarn workspaces, set env vars (INFURA key, WalletConnect project), then yarn dev to launch Next.js.
- E2E tests connect to a local Nitro test node.

##### Detail
- Next.js API route is represented (or group them under “API Routes”)
- That Token-Bridge-SDK is invoked by UI and API layers for transaction building
- Environment variables/config (INFURA_KEY, WC_PROJECT_ID) feeding into RPC and WalletConnect

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Frontend (React UI)" 
        style Frontend fill:#cce5ff,stroke:#2b6cb0,stroke-width:1px
        UI_Pages["src/pages/"]:::frontend
        UI_Components["src/components/"]:::frontend
        UI_Hooks["src/hooks/"]:::frontend
        UI_Styles["src/styles/tailwind.css"]:::frontend
        UI_Public["public/"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Next.js API)" 
        style Backend fill:#d5f5e3,stroke:#27ae60,stroke-width:1px
        API_Routes["src/pages/api/"]:::backend
    end

    %% SDK Layer
    subgraph "Token-Bridge-SDK" 
        style SDK fill:#d5f5e3,stroke:#239b56,stroke-width:1px
        SDK["src/token-bridge-sdk/"]:::backend
    end

    %% Data Fetching Layer
    subgraph "Subgraph Utilities" 
        style SubgraphUtils fill:#f5cba7,stroke:#d35400,stroke-width:1px
        Deposits["src/util/deposits/"]:::blockchain
        Teleports["src/util/teleports/"]:::blockchain
        Withdrawals["src/util/withdrawals/"]:::blockchain
        ServerSubgraph["src/api-utils/ServerSubgraphUtils.ts"]:::blockchain
    end

    %% RPC & WalletConnect
    subgraph "RPC & WalletConnect" 
        style RPC_WC fill:#f5cba7,stroke:#d35400,stroke-width:1px
        RPC_Util["src/util/rpc/"]:::blockchain
        Wagmi_Util["src/util/wagmi/"]:::blockchain
        WC_Utils["src/util/walletConnectUtils.ts"]:::blockchain
        WC_Setup["src/util/wagmi/setup.ts"]:::blockchain
    end

    %% External Services
    subgraph "Blockchain Networks & Services"
        style Blockchain fill:#f5cba7,stroke:#d35400,stroke-width:1px
        Ethereum["Ethereum L1 RPC"]:::blockchain
        Arbitrum["Arbitrum L2 RPC"]:::blockchain
        Orbit["Orbit Chains RPC"]:::blockchain
        SubgraphEndpoint["The Graph Subgraphs (Deposits, Teleports, Withdrawals)"]:::blockchain
        WalletConnectCloud["WalletConnect Service"]:::blockchain
        InfuraAlchemy["Infura / Alchemy / Custom RPC"]:::blockchain
    end

    %% CLI & Dev Tools
    subgraph "Dev & CI/CD" 
        style Dev fill:#e8e8e8,stroke:#7f8c8d,stroke-width:1px
        CI_CD[".github/workflows/ & vercel.json"]:::dev
        CLI_Scripts["packages/scripts/src/"]:::dev
        CLI_AddOrbit["packages/scripts/src/addOrbitChain/"]:::dev
        E2E_Tests["tests/e2e/"]:::dev
        Synpress_Config["synpress.config.ts"]:::dev
        UIDriver["src/ui-driver/"]:::dev
        Types["src/types/"]:::dev
        Constants["src/constants.ts"]:::dev
        Defaults["src/defaults.ts"]:::dev
    end

    %% Flows
    Browser["User Browser"]:::frontend -->|"HTTP/SSR & API Calls"| UI_Pages
    UI_Pages -->|"calls REST"| API_Routes
    UI_Components -->|"uses SDK"| SDK
    UI_Pages -->|"invokes"| SDK
    API_Routes -->|"GraphQL"| ServerSubgraph
    API_Routes -->|"> deposits/teleports/withdrawals"| Deposits
    SDK -->|"JSON-RPC"| RPC_Util
    RPC_Util -->|"to"| InfuraAlchemy
    Wagmi_Util -->|"to"| InfuraAlchemy
    WC_Utils -->|"connects via"| WalletConnectCloud
    WC_Setup -->|"configures"| WalletConnectCloud
    InfuraAlchemy -->|"to"| Ethereum
    InfuraAlchemy -->|"to"| Arbitrum
    InfuraAlchemy -->|"to"| Orbit
    SubgraphEndpoint -->|"provides data to"| ServerSubgraph

    CI_CD -->|"CI triggers build/deploy"| UI_Pages
    CLI_Scripts -->|"manage configs"| Defaults
    CLI_AddOrbit -->|"adds chain"| Defaults
    E2E_Tests -->|"test UI & SDK"| UI_Pages
    Synpress_Config -->|"configures tests"| E2E_Tests
    UIDriver -->|"integration tests"| SDK

    %% Click Events
    click UI_Pages "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/pages/"
    click UI_Components "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/components/"
    click UI_Hooks "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/hooks/"
    click UI_Styles "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/styles/tailwind.css"
    click UI_Public "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/public/"
    click API_Routes "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/pages/api/"
    click SDK "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/token-bridge-sdk/"
    click Deposits "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/util/deposits/"
    click Teleports "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/util/teleports/"
    click Withdrawals "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/util/withdrawals/"
    click ServerSubgraph "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/api-utils/ServerSubgraphUtils.ts"
    click RPC_Util "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/util/rpc/"
    click Wagmi_Util "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/util/wagmi/"
    click WC_Utils "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/util/walletConnectUtils.ts"
    click WC_Setup "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/util/wagmi/setup.ts"
    click CLI_Scripts "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/scripts/src/"
    click CLI_AddOrbit "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/scripts/src/addOrbitChain/"
    click E2E_Tests "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/tests/e2e/"
    click Synpress_Config "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/synpress.config.ts"
    click UIDriver "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/ui-driver/"
    click Types "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/packages/arb-token-bridge-ui/src/types/"
    click Constants "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/constants.ts"
    click Defaults "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/packages/arb-token-bridge-ui/src/defaults.ts"
    click CI_CD "https://github.com/offchainlabs/arbitrum-token-bridge/tree/master/.github/workflows/"
    click CI_CD "https://github.com/offchainlabs/arbitrum-token-bridge/blob/master/vercel.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#2b6cb0
    classDef backend fill:#d5f5e3,stroke:#27ae60
    classDef blockchain fill:#f5cba7,stroke:#d35400
    classDef dev fill:#e8e8e8,stroke:#7f8c8d
```
