# symbol/product architecture

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

- Interactive diagram: https://gitdiagram.com/symbol/product
- Repository: https://github.com/symbol/product

## Overview

##### Project type and purpose
- This repo is a polyglot, multi-component monorepo for the Symbol ecosystem. It bundles several independent microservices, full-stack UIs, SDK libraries, and CLI tools, all aimed at blockchain data exploration, bridging assets across chains, token faucets, network tooling, and client SDKs.

##### File structure
- Top-level folders = standalone sub-projects:
- bridge (Python service)
- explorer (frontend, rest API, nodewatch collector, puller scripts)
- faucet (authenticator, backend, frontend)
- lightapi/python (Python CFFI SDK)
- tools/shoestring and tools/vanity (Python CLIs)
- wallet/common/{core,ethereum,symbol} (JS wallet SDKs)
- Each sub-folder has its own src, tests, Dockerfile, CI scripts (Jenkinsfile or GitHub workflows).
- Patterns: microservice per directory, clear frontend/backend separation in “explorer” and “faucet,” shared libraries under “wallet/common” and “lightapi/python.”

##### README for additional insights
- The README enumerates each component’s CI status (lint, test, coverage), confirming that each is deployed/built/tested independently.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bridge Domain
    subgraph "Bridge Domain"
        direction TB
        BridgeService["Bridge Service (Python)"]:::backend
        BridgeDB[(Bridge DB)]:::db
        Vault["Vault (Secrets)"]:::external
        PriceOracle["Price Oracles"]:::external
        EthereumRPC["Ethereum RPC Nodes"]:::external
        SymbolRPC["Symbol RPC Nodes"]:::external
        BridgeService -->|"writes"| BridgeDB
        BridgeService -->|"reads secrets"| Vault
        BridgeService -->|"loads prices"| PriceOracle
        BridgeService -->|"push payouts"| EthereumRPC
        BridgeService -->|"push payouts"| SymbolRPC
    end

    %% Explorer Domain
    subgraph "Explorer Domain"
        direction TB
        ExplorerFrontend["Explorer Frontend (Next.js)"]:::ui
        ExplorerAPI["Explorer REST API (Python)"]:::backend
        ExplorerDB[(Explorer DB)]:::db
        NodeWatch["Node-watch Service"]:::backend
        Puller["Puller Scripts (cron)"]:::backend
        CoinGecko["Price Oracles"]:::external
        SymbolRPC2["Symbol RPC Nodes"]:::external

        ExplorerFrontend -->|"REST"| ExplorerAPI
        ExplorerAPI -->|"reads/writes"| ExplorerDB
        ExplorerAPI -->|"RPC"| SymbolRPC2
        ExplorerFrontend -->|"uses SDK"| WalletCore
        NodeWatch -->|"cron"| ExplorerDB
        Puller -->|"cron"| NodeWatch
    end

    %% Faucet Domain
    subgraph "Faucet Domain"
        direction TB
        FaucetFrontend["Faucet Frontend (Next.js)"]:::ui
        Authenticator["Authenticator (Twitter OAuth)"]:::backend
        FaucetBackend["Faucet Backend (Express)"]:::backend
        Vault2["Vault (Secrets)"]:::external
        NEMRPC["NEM/Symbol RPC Nodes"]:::external

        FaucetFrontend -->|"JWT auth"| Authenticator
        Authenticator -->|"issues JWT"| FaucetFrontend
        Authenticator -->|"calls"| FaucetBackend
        FaucetBackend -->|"RPC"| NEMRPC
        FaucetBackend -->|"reads secrets"| Vault2
        FaucetFrontend -->|"uses SDK"| WalletSymbol
    end

    %% SDKs Domain
    subgraph "Shared SDKs" 
        direction TB
        LightAPI["LightAPI Python SDK"]:::sdk
        WalletCore["Wallet SDK Core"]:::sdk
        WalletEthereum["Wallet SDK Ethereum"]:::sdk
        WalletSymbol["Wallet SDK Symbol"]:::sdk

        BridgeService -->|"uses SDK"| LightAPI
        ExplorerAPI -->|"uses SDK"| LightAPI
        FaucetBackend -->|"uses SDK"| LightAPI
    end

    %% Tools Domain
    subgraph "CLI Tools"
        direction TB
        Shoestring["Shoestring CLI"]:::backend
        Vanity["Vanity CLI"]:::backend
        Shoestring -->|"uses connectors"| LightAPI
        Vanity -->|"uses connectors"| LightAPI
    end

    %% External Services
    subgraph "External Networks & APIs"
        direction TB
        TwitterAPI["Twitter OAuth"]:::external
        VaultExt["Vault"]:::external
        PriceExt["CoinGecko/CoinMarketCap"]:::external
    end

    %% Wallet SDK dependencies
    ExplorerFrontend -->|"signing"| WalletCore
    ExplorerFrontend -->|"network calls"| WalletEthereum
    FaucetFrontend -->|"signing"| WalletCore
    FaucetFrontend -->|"network calls"| WalletSymbol

    %% Click Events
    click BridgeService "https://github.com/symbol/product/tree/dev/bridge/bridge"
    click ExplorerFrontend "https://github.com/symbol/product/tree/dev/explorer/frontend"
    click ExplorerAPI "https://github.com/symbol/product/tree/dev/explorer/rest/rest"
    click NodeWatch "https://github.com/symbol/product/tree/dev/explorer/nodewatch/nodewatch"
    click Puller "https://github.com/symbol/product/tree/dev/explorer/nodewatch/puller"
    click Authenticator "https://github.com/symbol/product/tree/dev/faucet/authenticator/src"
    click FaucetBackend "https://github.com/symbol/product/tree/dev/faucet/backend/src"
    click FaucetFrontend "https://github.com/symbol/product/tree/dev/faucet/frontend"
    click LightAPI "https://github.com/symbol/product/tree/dev/lightapi/python"
    click Shoestring "https://github.com/symbol/product/tree/dev/tools/shoestring/shoestring"
    click Vanity "https://github.com/symbol/product/tree/dev/tools/vanity/vanity"
    click WalletCore "https://github.com/symbol/product/tree/dev/wallet/common/core/src"
    click WalletEthereum "https://github.com/symbol/product/tree/dev/wallet/common/ethereum/src"
    click WalletSymbol "https://github.com/symbol/product/tree/dev/wallet/common/symbol/src"

    %% Styles
    classDef ui fill:#E3F2FD,stroke:#1976D2,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#388E3C,color:#1B5E20;
    classDef db fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238;
    classDef sdk fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
```
