# Architecture Overview ## System Diagram ``` ┌─────────────────────────────────────────────────────────┐ │ User Interfaces │ │ │ │ noelclaw.fun noelapp (React 19 + Vite) │ │ (Landing Page) (Full Platform) │ │ │ │ │ Privy Auth (OAuth) │ └────────────────────────────┼─────────────────────────────┘ │ ┌────────────────────────────▼─────────────────────────────┐ │ Convex Backend │ │ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ Queries │ │ Mutations │ │ Actions │ │ │ │ (real-time) │ │ (DB writes) │ │ (node.js env) │ │ │ └──────────────┘ └──────────────┘ └───────┬───────┘ │ │ │ │ │ ┌────────────────────────────────────────────▼───────┐ │ │ │ HTTP Router (convex.site) │ │ │ │ /mcp/market /mcp/chat /mcp/research/* │ │ │ │ /mcp/signals/* /mcp/whale-alerts │ │ │ │ /mcp/defi/* /mcp/wallet/* │ │ │ │ /user/telegram /alchemy/deposit │ │ │ └────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ┌───────▼──────┐ ┌──────────▼────────┐ ┌────────▼─────┐ │ Bankr LLM + │ │ 0x Permit2 API │ │ Grok API │ │ Agent APIs │ │ swap routing │ │ X sentiment │ │ (all agents) │ │ Base mainnet │ │ analysis │ └──────────────┘ └───────────────────┘ └──────────────┘ │ ┌──────────▼─────────┐ │ Privy Server │ │ Wallet API │ │ (DeFi execution) │ └────────────────────┘ │ ┌──────────▼─────────┐ │ Telegram Bot API │ │ (shift reports) │ └────────────────────┘ ┌────────────────┐ │ MCP Server │ │ (noelclaw-mcp)│ │ stdio/HTTP │ └───────┬────────┘ │ ┌─────────────────┼──────────────────┐ │ │ │ ┌──────▼──────┐ ┌───────▼──────┐ ┌───────▼──────┐ │ Hermes │ │ Claude Code │ │ Cursor / │ │ OpenClaw │ │ Desktop │ │ Windsurf │ └─────────────┘ └──────────────┘ └──────────────┘ ``` *** ## Frontend Stack | Layer | Technology | | --------- | ------------------------------------------ | | Framework | React 19.2.0 + TypeScript | | Build | Vite 7.2.4 | | Styling | TailwindCSS 3.4 + Radix UI | | Animation | Framer Motion 12.38, GSAP | | State | Zustand | | Data | Convex React SDK (real-time) | | Auth | Privy SDK | | Web3 | Wagmi 3.6 + Viem 2.48 + Ethers 6.16 | | Payments | x402 protocol (Base mainnet) | | Games | Phaser 3.90 (PokemonAutoChess), Canvas API | *** ## Backend Stack (Convex) Convex is the entire backend — database, serverless functions, scheduling, and HTTP router in one. | Layer | Details | | ---------- | -------------------------------------------------------------------------------------------------------------- | | Database | Convex (document DB with real-time subscriptions) | | Serverless | Actions (`"use node"`) for external API calls | | Scheduling | Cron jobs: research (5 min), signals (daily 08:00 UTC), whale alerts (hourly), weekly recap (Sunday 23:55 UTC) | | HTTP | `convex.site` endpoints for MCP + webhooks | | Auth | JWT validation via Privy tokens | *** ## Data Flow: User Sends Chat Message ``` User types message │ ▼ React component (Chat.tsx) │ ▼ Convex action: api.chat.chat │ ▼ Bankr LLM gateway (https://llm.bankr.bot) → model: gpt-5-nano / claude-sonnet-4-6 │ ▼ Response streamed back │ ▼ Convex mutation: save to DB │ ▼ React re-renders (real-time subscription) ``` *** ## Data Flow: Research Shift ``` User calls start_research (MCP or UI) │ ▼ HTTP POST /mcp/research/start │ ▼ Convex action: researchEngine.startResearchShift → creates researchJob in DB → kicks off initial data collection → sends Telegram start notification │ ▼ (every 5 min, cron) researchEngine.checkAndCollect → for each active job where 30min elapsed: CoinGecko trending + movers Grok X/Twitter sentiment Bankr on-chain signals → saves to researchDataPoints │ ▼ (every 5 min, cron) researchEngine.checkAndReport → at 2.5h: generate interim report → Telegram → at 5h: generate interim report → Telegram → at 8h: generate final report → Telegram → complete job ``` *** ## Data Flow: Trading Signal (Daily) ``` Convex cron fires at 08:00 UTC │ ▼ signalEngine.ts — internalAction → sends 1H market analysis prompt to Bankr LLM → parses JSON: signal, entry, TP1, TP2, SL, confidence → saves to tradingSignals table → sends Telegram signal card │ ▼ (every 30 min, cron) outcomeTracker.ts → fetches live price from Bankr → for each PENDING signal: if price >= TP1 → WIN if price <= SL → LOSS if age > 6h → EXPIRED → updates tradingSignals record ``` *** ## Data Flow: Weekly Recap (Sunday) ``` Convex cron fires Sunday at 23:55 UTC │ ▼ weeklyRecap.ts — internalAction → queries tradingSignals for Mon–Sun window → builds per-day map (BTC + ETH signals) → calculates wins, losses, PnL stats → sends Bankr LLM prompt for AI review → saves to weeklyRecaps table → sends full Telegram recap card ``` *** ## Data Flow: Whale Alerts (Hourly) ``` Convex cron fires every hour │ ▼ whaleAlerts.ts — internalAction → sends whale detection prompt to Bankr Agent API → polls Bankr job until complete → parses alert list (CEX flows, large transfers, smart money) → saves to whaleAlerts table → sends Telegram alert card ``` *** ## Data Flow: DeFi Wallet (MCP) ``` MCP client calls connect_wallet / swap_tokens / send_token │ ▼ HTTP POST /mcp/defi/* → Convex HTTP router │ ▼ defi.ts — internalAction For connect_wallet: → check connectedWallets table → if none: POST https://auth.privy.io/api/v1/wallets → save walletId + address to DB For swap_tokens: → GET 0x Permit2 quote (chainId=8453) → if approval needed: sign + send approve tx via Privy RPC → sign EIP-712 permit2 typed data via Privy → send swap tx with signature appended For send_token: → ETH: sign eth_sendTransaction via Privy RPC → ERC-20: encode transfer() calldata, sign + send ``` *** ## MCP Architecture The MCP server (`noelclaw-mcp`) is a standalone Node.js process that: 1. Speaks the Model Context Protocol over **stdio** 2. Proxies all tool calls to the Convex HTTP API (`convex.site`) 3. Formats responses for the AI client No secrets are stored in the MCP server. All API keys live in Convex environment variables on the server side. *** ## Security Model * **API keys** — stored as Convex env vars, never in client bundle * **Wallet keys** — encrypted before storing in DB * **Auth** — Privy JWT tokens validated per request * **MCP** — stateless; all calls require valid Convex session or are anonymous * **Payments** — x402 protocol, on-chain verification via Base mainnet --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.noelclaw.fun/getting-started/architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.