How 0xoucan/mictlai-mantlequest works
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.