Architecture

System Overview

┌─────────────────────────────────────────────────────┐
│                   Host Application                   │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │         TokenFlight SDK (Web Component)         │  │
│  │                                                  │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │  │
│  │  │ Swap UI  │  │Receive UI│  │ Token Selector│  │  │
│  │  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │  │
│  │       │              │               │           │  │
│  │  ┌────▼──────────────▼───────────────▼───────┐  │  │
│  │  │           State Machine                    │  │  │
│  │  │  idle → quoting → quoted → building →      │  │  │
│  │  │  awaiting-wallet → submitting → tracking   │  │  │
│  │  └────────────────┬──────────────────────────┘  │  │
│  │                   │                              │  │
│  │  ┌────────────────▼───────────────────────────┐ │  │
│  │  │         TanStack Solid Query               │ │  │
│  │  │    (caching, deduplication, polling)        │ │  │
│  │  └────────────────┬───────────────────────────┘ │  │
│  └───────────────────┼─────────────────────────────┘  │
│                      │                                 │
└──────────────────────┼─────────────────────────────────┘
                       │ HTTPS
          ┌────────────▼────────────┐
          │   Hyperstream API       │
          │   (your API endpoint)   │
          │                         │
          │  POST /v1/quotes        │
          │  POST /v1/deposit/build │
          │  PUT  /v1/deposit/submit│
          │  GET  /v1/orders/:addr  │
          │  GET  /v1/tokens/search │
          │  GET  /v1/chains        │
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │    Routing Layer        │
          │    Intent Settlement    │
          │                         │
          │  Route Providers:       │
          │  • Multiple bridge      │
          │    protocols            │
          └────────────┬────────────┘
                       │
     ┌─────────────────┼─────────────────┐
     │                 │                  │
┌────▼────┐      ┌────▼────┐      ┌─────▼────┐
│ Source   │      │ Bridge  │      │  Dest    │
│ Chain    │      │ Network │      │  Chain   │
│(Ethereum)│      │         │      │  (Base)  │
└─────────┘      └─────────┘      └──────────┘

Data Flow

1. User Interaction → Quote

User selects tokens and amount
  → SDK sends POST /v1/quotes to the API
  → API returns route options from available providers
  → SDK displays routes in the UI
  → onQuoteReceived callback fires

2. Route Selection → Build

User selects a route
  → SDK sends POST /v1/deposit/build
  → API returns wallet actions (approve + transfer)
  → SDK prepares transaction for wallet signing

3. Wallet Signing → Submit

SDK passes transaction to Wallet Adapter
  → Adapter calls wallet (MetaMask, Phantom, etc.)
  → User signs in wallet popup
  → SDK receives txHash
  → SDK sends PUT /v1/deposit/submit with txHash
  → API creates order and begins tracking

4. Order Tracking → Completion

SDK polls GET /v1/orders/:address
  → Progressive polling: 1s → 2s → 3s → 5s → 10s intervals
  → API returns order status updates
  → SDK updates UI (tracking progress bar)
  → Order reaches "filled" status
  → onSwapSuccess callback fires

Wallet Adapter Layer

┌──────────────────────────────────────────────┐
│              IWalletAdapter                   │
│                                               │
│  connect()  getAddress()  executeWalletAction()│
│  disconnect()  isConnected()  on() / off()   │
└──────────┬──────────┬──────────┬─────────────┘
           │          │          │
    ┌──────▼──┐ ┌────▼─────┐ ┌─▼──────────┐
    │ AppKit  │ │  wagmi   │ │  ethers    │
    │ Adapter │ │  Adapter │ │  Adapter   │
    │         │ │          │ │            │
    │EVM+Sol  │ │ EVM only │ │ EVM only   │
    └────┬────┘ └────┬─────┘ └─────┬──────┘
         │           │             │
    ┌────▼────┐ ┌────▼─────┐ ┌────▼──────┐
    │Reown    │ │ wagmi    │ │window.    │
    │AppKit   │ │ Core     │ │ethereum   │
    └─────────┘ └──────────┘ └───────────┘

Shadow DOM Isolation

Each widget instance creates its own Shadow DOM:

<div id="swap-widget">          ← Host element (your DOM)
  └── <div>                     ← Shadow host (created by SDK)
       └── #shadow-root (open)  ← Shadow boundary
            ├── <style>         ← Scoped CSS (theme + base styles)
            └── <div>           ← Solid.js mount point
                 └── ...        ← Widget UI components

Styles inside the Shadow DOM don't leak out, and page styles don't leak in. The supported customization paths are CSS custom properties (--tf-*) and the setCustomColors() runtime method.

Caching Architecture

┌──────────────────────────────────┐
│     TanStack Solid Query         │
│     (shared QueryClient)         │
│                                  │
│  Cached:                         │
│  • Chain list (GET /v1/chains)   │
│  • Token metadata                │
│  • Wallet balances               │
│  • Quote responses               │
│                                  │
│  Shared across widget instances  │
│  Cleared on destroy()            │
└──────────────────────────────────┘

Multiple widget instances on the same page share the same QueryClient, deduplicating API requests automatically.