How javabridge/javabridge-next works
Project Type and Purpose
• This is a full-stack web application built with Next.js. The primary functions are:
• ETH bridging between chains (Arbitrum Sepolia, Gayo Roll, Bali Beans) by interfacing with blockchain RPC endpoints.
• Serving an AI Agent that integrates RAG for delivering Espresso-related information and real-time crypto insights via the Pyth API.
• The README further outlines that the AI agent has a persona, integrates external knowledge sources (including local documents for Espresso), and that these systems co-exist in a single cohesive application.
File Structure
• API Endpoints (found under app/api):
• The “agent” directory contains several endpoint files such as characters.js, create-agent.ts, and others that indicate the backend logic responsible for the AI Agent.
• The “embedding” directory houses endpoints for creating and searching document embeddings, which are integral to the RAG pipeline.
• Chat Modules (in app/chat):
• Contains React components (chat-guide, chat-input, chat-message, typing-indicator) and a page file that support the chat interface for the AI Agent.
• Bridge and Network:
• Directory “lib” has subdirectories under action-providers (bridge, math, rag, template) that encapsulate business logic related to bridging and AI functionalities.
• Several files (lib/chains.js, lib/contracts.js) are found that clearly relate to blockchain interactions and configuring network details.
• UI Components:
• The “components” and “components/ui” directories hold reusable UI elements like avatar, button, card, input, etc., which are used across the application pages like network, chat, or the main app layout.
• External Documentation:
• The “embedding_docs” directory contains input and output document directories, likely sources for the RAG agent to process detailed Espresso knowledge.
A. Main Components:
• Frontend:
• Pages: Main landing page (app/page.jsx), Network page (app/network/page.jsx), Chat page (app/chat/page.jsx).
• UI Components: Reusable components (Bridge, MobileMenu, Chat Components) located under “app/components” and “components/ui”.
• Providers and Hooks: For managing global state and agent-specific behavior (e.g. useAgent.ts).
• API Layer / Backend:
• Agent & Embedding API: Under app/api/agent and app/api/embedding provide endpoints for creating agents, handling chat interactions, and performing RAG-based embedding operations.
• Additional utility libraries in “lib” that contain logic for bridging (action-providers/bridge), math, rag computations, and blockchain specific routines.
• External Services:
• Blockchain RPC endpoints (configured in the README for supported chains).
• Pyth network for real-time cryptocurrency prices.
• Data & Documentation:
• Local embedding docs used for knowledge retrieval in the RAG pipeline.
B. Relationships and Interactions:
• How the Frontend communicates with the API endpoints via Next.js routing.
• That the API layer uses functions in the “lib” folder to execute specific business processes (e.g., bridging logic, RAG pipelines).
• Connection from the AI Agent endpoints to the external Pyth API and reference the data inputs from “embedding_docs”.
• Flow where user interactions (chat queries, ETH bridging instructions) trigger API calls that then interact with smart contract functions (chains and contracts files) and external networks.
C. Architectural Patterns and Design Principles:
• Use the component-based design of Next.js — separate presentation and logic layers.
• MVC-like separation: Frontend UI/Pages, API Routes acting as Controllers, and Lib modules serving as Models/Services.
• Integration of modern server-side capabilities (Next.js API routes) that communicate with blockchain services and external APIs.
• The RAG pattern in the AI Agent with document retrieval followed by language model generation.
D. Relevant Technologies & Frameworks:
• Next.js framework running on Node.js.
• Tailwind CSS (tailwind.config.js) for UI styling.
• External Blockchain RPC endpoints and Web3 libraries (e.g., lib/web3-call.js).
• Integration with Pyth Network for crypto price feeds.
• JavaScript/TypeScript for API and frontend components.