# 0xoucan/mictlai-mantlequest architecture

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

- Interactive diagram: https://gitdiagram.com/0xoucan/mictlai-mantlequest
- Repository: https://github.com/0xoucan/mictlai-mantlequest

## Overview

##### Project Type and Purpose
- This is a full-stack AI-powered cross-chain bridge application (“MictlAI”) with two primary modules:
- Backend (celo-mind-dn): Node.js/TypeScript service that orchestrates AI commands, protocol integrations, and blockchain operations.
- Frontend (celo-mind-web): React/TypeScript/Vite web UI that provides an AI chat interface, wallet management, and transaction monitoring.

##### Key Architectural Components
a. Frontend
- React App: main.tsx → App.tsx
- UI Components: ChatInterface, WalletBalances, TransactionMonitor, LiquidityMonitor, InfoPanel, etc.
- Context Providers: WalletContext, PrivyProvider for auth & wallet state.
- Services: agentService (calls AI API), blockchainService (viem/ethers for on-chain reads), transactionService (status polling).
- Static Assets & Config: index.html, tailwind.config.js, vite.config.ts.
b. Backend
- API Server: src/api-server.ts (Express + CORS + streaming).
- Chatbot/Agent: src/chatbot.ts orchestrates natural-language parsing, AI calls, session management.
- Action Providers: plugin-style modules under src/action-providers (Aave, Nebula, Lendle, Treehouse, MerchantMoe, AtomicSwaps, etc.) that define per-protocol schemas, errors, build transactions, and walletScanner logic.
- Services: src/services (atomic-swap-relay, other blockchain helpers).
- Utilities: src/utils (logger, rate-limiter, transaction-utils).
- Telegram Interface: src/telegram-interface.ts for optional CLI/chatbot mode.
c. External Services
- Blockchain Networks: Base, Arbitrum, Mantle, zkSync Era via RPC endpoints.
- Nebula AI Platform: thirdweb’s AI endpoints for NLP and strategy recommendations.
- Wallet Providers: Browser extension wallets (MetaMask, Rabby) or private key (CLI mode).
- Telegram Bot API (optional).

##### Relationships and Data Flows
1. User interacts via web UI or Telegram.
2. Frontend captures natural-language request in ChatInterface.
3. Frontend → HTTP/S streaming call to Backend `/api/agent/chat`.
4. Backend chatbot orchestrator:
- Parses intent → selects appropriate ActionProvider(s).
- Calls Nebula AI for NLP and strategy guidance.
- Constructs transaction payload(s) or cross-chain swap requests.
5. Backend returns streaming JSON to Frontend with proposed actions.
6. Frontend displays suggestions. Upon user approval:
- Frontend uses blockchainService to send unsigned tx payload to wallet.
- Wallet signs & submits to target blockchain network.
7. Frontend → Backend transactionService polls status via Explorer APIs or backend relay.
8. Status updates flow back to UI; WalletBalances, TransactionMonitor, LiquidityMonitor refresh accordingly.

##### Architectural Patterns and Design Principles
- Plugin Architecture: action-providers are self-contained modules for each DeFi protocol.
- Separation of Concerns: clear split between AI orchestration (chatbot), protocol logic (providers), transport (API server), client UI, and blockchain interactions.
- Streaming Responses: real-time UI updates during AI processing.
- Contextual Session Management: chatbot retains conversation memory for follow-up commands.
- Secure Wallet Handling: no private keys in web—transactions signed client-side.

##### Detailed Elements
- Clear labels: component names, file paths (e.g., api-server.ts, ChatInterface.tsx).
- Data flows: Chat request, AI response, Transaction payload, Signed TX, Status Poll.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React App)" 
        direction TB
        A1["main.tsx"]:::frontend
        A2["App.tsx"]:::frontend
        subgraph "UI Components"
            direction TB
            CI["ChatInterface.tsx"]:::frontend
            WB["WalletBalances.tsx"]:::frontend
            TM["TransactionMonitor.tsx"]:::frontend
            LM["LiquidityMonitor.tsx"]:::frontend
            IP["InfoPanel.tsx"]:::frontend
            WC["WalletConnect.tsx"]:::frontend
            H["Header.tsx"]:::frontend
            ML["MainLayout.tsx"]:::frontend
        end
        subgraph "Context Providers"
            direction TB
            WCtx["WalletContext.tsx"]:::frontend
            PP["PrivyProvider.tsx"]:::frontend
        end
        subgraph "Services"
            direction TB
            ASvc["agentService.ts"]:::frontend
            BSvc["blockchainService.ts"]:::frontend
            TSvc["transactionService.ts"]:::frontend
        end
        subgraph "Config & Assets"
            direction TB
            IHTML["index.html"]:::frontend
            TConfig["tailwind.config.js"]:::frontend
            VConfig["vite.config.ts"]:::frontend
            GStyles["index.css"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Node.js/TypeScript)" 
        direction TB
        API["api-server.ts"]:::backend
        BOT["chatbot.ts"]:::backend
        TI["telegram-interface.ts"]:::backend
        subgraph "Action Providers (Plugins)"
            direction TB
            AP1["aave/index.ts"]:::plugin
            AP2["basic-atomic-swaps/index.ts"]:::plugin
            AP3["merchant-moe/index.ts"]:::plugin
            AP4["nebula/index.ts"]:::plugin
            AP5["treehouse-protocol/index.ts"]:::plugin
            AP6["lendle-protocol/index.ts"]:::plugin
            AP7["mento-swap/index.ts"]:::plugin
            AP8["ichi-vault/index.ts"]:::plugin
            AP9["cUSDescrowforiAmigoP2P/index.ts"]:::plugin
            AP10["balance-checker/index.ts"]:::plugin
            AP11["init-capital/index.ts"]:::plugin
        end
        subgraph "Services & Utils"
            direction TB
            SR["atomic-swap-relay.ts"]:::backend
            UL["logger.ts"]:::backend
            UR["rate-limiter.ts"]:::backend
            UT["transaction-utils.ts"]:::backend
            NC["network.ts"]:::backend
            Cst["constants/network.ts"]:::backend
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RPC["RPC Nodes (Base, Arbitrum, Mantle, zkSync)"]:::external
        NAI["Nebula AI"]:::external
        TBot["Telegram Bot API"]:::external
        Wallets["Browser Wallets (MetaMask, Rabby)"]:::external
    end

    %% User Entry Points
    User["User"]:::external
    subgraph "UI/CLI"
        direction TB
        WebUI["Web UI"]:::frontend
        TUI["Telegram UI"]:::external
    end

    %% Connections
    User -->|interacts via| WebUI
    User -->|interacts via| TUI
    WebUI -->|renders| A1
    A1 --> A2
    A2 --> CI
    A2 --> WB
    A2 --> TM
    A2 --> LM
    A2 --> IP
    A2 --> WC
    A2 --> H
    A2 --> ML
    CI -->|uses| ASvc
    WB -->|uses| BSvc
    TM -->|uses| TSvc
    LM -->|uses| TSvc
    ASvc -->|HTTP/S stream JSON chat| API
    TUI -->|Telegram requests| TI
    TI -->|invokes| BOT
    API -->|forwards chat| BOT
    BOT -->|selects provider| AP1 & AP2 & AP3 & AP4 & AP5 & AP6 & AP7 & AP8 & AP9 & AP10 & AP11
    BOT -->|calls NLP| NAI
    BOT -->|constructs tx| SR
    SR --> UT
    BOT -->|logs| UL
    BOT -->|rate limits| UR
    BOT -->|network configs| NC & Cst
    AP1 & AP2 & AP3 & AP4 & AP5 & AP6 & AP7 & AP8 & AP9 & AP10 & AP11 -->|builds tx payload| BSvc
    BSvc -->|sends unsigned tx| Wallets
    Wallets -->|signed TX| RPC
    RPC -->|tx receipt| TSvc
    TSvc -->|status poll| API
    API -->|status updates| TSvc
    TSvc -->|updates| TM & WB & LM

    %% Click Events
    click A1 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/main.tsx"
    click A2 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/App.tsx"
    click CI "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/ChatInterface.tsx"
    click WB "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/WalletBalances.tsx"
    click TM "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/TransactionMonitor.tsx"
    click LM "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/LiquidityMonitor.tsx"
    click IP "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/InfoPanel.tsx"
    click WC "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/WalletConnect.tsx"
    click H "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/Header.tsx"
    click ML "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/components/MainLayout.tsx"
    click WCtx "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/providers/WalletContext.tsx"
    click PP "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/providers/PrivyProvider.tsx"
    click ASvc "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/services/agentService.ts"
    click BSvc "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/services/blockchainService.ts"
    click TSvc "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/services/transactionService.ts"
    click IHTML "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/index.html"
    click TConfig "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/tailwind.config.js"
    click VConfig "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/vite.config.ts"
    click GStyles "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-web/src/index.css"
    click API "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/api-server.ts"
    click BOT "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/chatbot.ts"
    click TI "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/telegram-interface.ts"
    click AP1 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/aave/index.ts"
    click AP2 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/basic-atomic-swaps/index.ts"
    click AP3 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/merchant-moe/index.ts"
    click AP4 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/nebula/index.ts"
    click AP5 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/treehouse-protocol/index.ts"
    click AP6 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/lendle-protocol/index.ts"
    click AP7 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/mento-swap/index.ts"
    click AP8 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/ichi-vault/index.ts"
    click AP9 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/cUSDescrowforiAmigoP2P/index.ts"
    click AP10 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/balance-checker/index.ts"
    click AP11 "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/action-providers/init-capital/index.ts"
    click SR "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/services/atomic-swap-relay.ts"
    click UL "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/utils/logger.ts"
    click UR "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/utils/rate-limiter.ts"
    click UT "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/utils/transaction-utils.ts"
    click NC "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/network/network.ts"
    click Cst "https://github.com/0xoucan/mictlai-mantlequest/blob/main/celo-mind-dn/src/constants/network.ts"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef plugin fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
```
