# bnb-chain/canonical-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/bnb-chain/canonical-bridge
- Repository: https://github.com/bnb-chain/canonical-bridge

## Overview

##### Project type and purpose
- This is a monorepo for a full-stack, modular token-bridge solution on BNB Chain, comprised of:
- a NestJS-based data service (“canonical-bridge-server”)
- a Next.js/React UI (“canonical-bridge-ui”)
- a reusable TypeScript SDK (“canonical-bridge-sdk”)
- an embeddable React widget (“canonical-bridge-widget”)
- The purpose is to let end-users and integrators perform and display cross-chain token transfers via multiple bridge protocols (cBridge, deBridge, Stargate, LayerZero, Meson).

##### File structure
- Top-level directories:
- apps/ – contains two runnable services: server (NestJS + Prisma + Redis) and UI (Next.js)
- packages/ – two libraries: sdk (core adapters & aggregator) and widget (React component + UI modules)
- common/ – monorepo tooling, Rush config, git hooks, CI scripts
- Server structure follows NestJS modules (bridge, token, health), shared services (database, Prisma, ioredis, web3) and background processors/schedulers.
- UI is a Next.js project with pages, core components, theme, wallet integration, and static assets.
- SDK contains adapters per protocol, core logic, and aggregator.
- Widget wraps the SDK + React components, hooks, providers, and contract abstractions for easy integration.

##### README for additional insights
- Confirms multi-bridge support and cross-chain transfer features.
- Describes the data service (server), the example UI, the SDK, and the widget.
- Points to GitHub Actions for CI/CD and Rush for monorepo management.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo & CI/CD
    subgraph "Monorepo & CI/CD"
        Rush["rush.json"]:::tool
        Common["common/"]:::tool
        GitHubCI[".github/workflows/"]:::tool
    end

    %% Data Service
    subgraph "Data Service (canonical-bridge-server)" 
        BCtr["BridgeController"]:::backend
        BServ["BridgeService"]:::backend
        BProc["BridgeProcessor"]:::backend
        BSched["BridgeScheduler"]:::backend

        TCtr["TokenController"]:::backend
        TServ["TokenService"]:::backend
        TProc["TokenProcessor"]:::backend
        TSched["TokenScheduler"]:::backend

        HCtr["HealthController"]:::backend

        subgraph "Shared Services"
            Prisma["Prisma Service"]:::backend
            RedisSvc["ioredis Service"]:::backend
            Web3Svc["Web3 Service"]:::backend
        end

        DB["PostgreSQL"]:::external
        Cache["Redis"]:::external
        Chains["Blockchains & Contracts"]:::external
    end

    %% Next.js UI
    subgraph "Next.js UI (canonical-bridge-ui)"
        Pages["Pages"]:::frontend
        Layout["Layout Components"]:::frontend
        Theme["ThemeProvider"]:::frontend
        WalletProv["WalletProvider"]:::frontend
    end

    %% SDK
    subgraph "TypeScript SDK (canonical-bridge-sdk)"
        Adapters["Adapters"]:::library
        Aggregator["SDK Aggregator"]:::library
        CoreSDK["Core Logic"]:::library
    end

    %% Widget
    subgraph "React Widget (canonical-bridge-widget)"
        WidgetIndex["Widget Entry (index.tsx)"]:::library
        WidgetProv["CanonicalBridgeProvider"]:::library
        AggMod["Aggregator Module"]:::library
        TransferMod["Transfer Module"]:::library
        WalletMod["Wallet Module"]:::library
    end

    %% External
    UserApp["User/Integrator App"]:::external

    %% Relationships
    UserApp -->|"embed widget"| WidgetIndex
    WidgetIndex -->|"initialize provider"| WidgetProv
    WidgetIndex -->|"calls SDK"| Aggregator
    WidgetProv -.->|"RPC call"| Chains
    Aggregator -->|"adapter call"| Adapters
    Aggregator -->|"core logic"| CoreSDK

    Pages -->|"GET /fees"| BCtr
    Pages -->|"GET /tokens"| TCtr
    Pages -->|"GET /health"| HCtr
    Pages -->|"uses SDK"| CoreSDK

    BCtr -->|"calls"| BServ
    BServ -->|"persist/query"| Prisma
    BServ -->|"cache"| RedisSvc
    BServ -->|"fetch on-chain"| Web3Svc
    BServ -->|"schedule job"| BSched
    BProc -->|"process jobs"| BServ

    TCtr -->|"calls"| TServ
    TServ -->|"persist/query"| Prisma
    TServ -->|"cache"| RedisSvc
    TServ -->|"fetch on-chain"| Web3Svc
    TServ -->|"schedule job"| TSched
    TProc -->|"process jobs"| TServ

    BSched -->|"publish job"| BProc
    TSched -->|"publish job"| TProc

    Prisma -->|"migrations/schema"| DB
    RedisSvc -->|"store/read"| Cache
    Web3Svc -->|"RPC"| Chains

    GitHubCI -->|"build/test"| Rush
    GitHubCI -->|"pipeline"| Common
    Rush -->|"install & build"| Adapters
    Rush -->|"install & build"| Aggregator
    Rush -->|"install & build"| CoreSDK
    Rush -->|"install & build"| WidgetIndex
    Rush -->|"install & build"| Pages

    %% Click Events
    click Rush "https://github.com/bnb-chain/canonical-bridge/blob/main/rush.json"
    click Common "https://github.com/bnb-chain/canonical-bridge/tree/main/common/"
    click GitHubCI "https://github.com/bnb-chain/canonical-bridge/tree/main/.github/workflows/"
    click BCtr "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/bridge/bridge.controller.ts"
    click BServ "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/bridge/bridge.service.ts"
    click BProc "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/bridge/bridge.processor.ts"
    click BSched "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/bridge/bridge.schedule.ts"
    click TCtr "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/token/token.controller.ts"
    click TServ "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/token/token.service.ts"
    click TProc "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/token/token.processor.ts"
    click TSched "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/token/token.schedule.ts"
    click HCtr "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/module/health/health.controller.ts"
    click Prisma "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/shared/prisma/prisma.service.ts"
    click RedisSvc "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/shared/ioredis/ioredis.service.ts"
    click Web3Svc "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/src/shared/web3/web3.service.ts"
    click DB "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-server/prisma/schema.prisma"
    click Cache "https://github.com/bnb-chain/canonical-bridge/tree/main/apps/canonical-bridge-server/prisma/migrations/"
    click Pages "https://github.com/bnb-chain/canonical-bridge/tree/main/apps/canonical-bridge-ui/pages/"
    click Layout "https://github.com/bnb-chain/canonical-bridge/tree/main/apps/canonical-bridge-ui/core/components/Layout"
    click Theme "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-ui/core/components/ThemeProvider/index.tsx"
    click WalletProv "https://github.com/bnb-chain/canonical-bridge/blob/main/apps/canonical-bridge-ui/core/wallet/WalletProvider.tsx"
    click Adapters "https://github.com/bnb-chain/canonical-bridge/tree/main/packages/canonical-bridge-sdk/src/adapters/"
    click Aggregator "https://github.com/bnb-chain/canonical-bridge/blob/main/packages/canonical-bridge-sdk/src/aggregator/index.ts"
    click CoreSDK "https://github.com/bnb-chain/canonical-bridge/blob/main/packages/canonical-bridge-sdk/src/core/index.ts"
    click WidgetIndex "https://github.com/bnb-chain/canonical-bridge/blob/main/packages/canonical-bridge-widget/src/index.tsx"
    click WidgetProv "https://github.com/bnb-chain/canonical-bridge/blob/main/packages/canonical-bridge-widget/src/CanonicalBridgeProvider.tsx"
    click AggMod "https://github.com/bnb-chain/canonical-bridge/tree/main/packages/canonical-bridge-widget/src/modules/aggregator/"
    click TransferMod "https://github.com/bnb-chain/canonical-bridge/tree/main/packages/canonical-bridge-widget/src/modules/transfer/"
    click WalletMod "https://github.com/bnb-chain/canonical-bridge/tree/main/packages/canonical-bridge-widget/src/modules/wallet/"

    %% Styles
    classDef external fill:#e0ffe0,stroke:#008000,color:#006400
    classDef backend fill:#e0f0ff,stroke:#005b96,color:#034f84
    classDef frontend fill:#fff8dc,stroke:#ffd700,color:#b8860b
    classDef library fill:#ffe4e1,stroke:#ff4500,color:#8b0000
    classDef tool fill:#f0f0f0,stroke:#a9a9a9,color:#696969
```
