# javabridge/javabridge-next architecture

> Architecture diagram of the GitHub repository javabridge/javabridge-next, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javabridge/javabridge-next
- Repository: https://github.com/javabridge/javabridge-next

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        subgraph "Pages"
            PageMain["Main Landing Page"]:::frontend
            PageNetwork["Network Page"]:::frontend
            PageChat["Chat Page"]:::frontend
        end
        subgraph "UI Components"
            BridgeUI["Bridge UI"]:::frontend
            BridgeHandler["Bridge Handler"]:::frontend
            MobileMenu["Mobile Menu"]:::frontend
            ChatComponents["Chat UI Components"]:::frontend
            ReusableUI["Reusable UI Elements"]:::frontend
        end
        subgraph "State & Hooks"
            AgentHooks["Agent Hooks"]:::frontend
            Providers["Providers"]:::frontend
        end
    end

    %% Backend / API Layer
    subgraph "API & Business Logic"
        %% Agent Services
        subgraph "Agent Services"
            AgentAPI["Agent API"]:::backend
            RAGProvider["RAG Provider"]:::backend
            AgentAPI -->|"calls"| RAGProvider
        end

        %% Embedding Service
        subgraph "Embedding Service"
            EmbeddingAPI["Embedding API"]:::backend
            EmbeddingLogic["Embedding Logic"]:::backend
            EmbeddingAPI -->|"processes"| EmbeddingLogic
        end

        %% Bridging Services
        subgraph "Bridging Services"
            Chains["Chains Module"]:::backend
            Contracts["Contracts Module"]:::backend
            Web3Call["Web3 Call Module"]:::backend
            BridgeProvider["Bridge Provider"]:::backend
            Chains -->|"uses"| Contracts
            Contracts -->|"calls"| Web3Call
            Web3Call -->|"integrates"| BridgeProvider
        end
    end

    %% External Services
    subgraph "External Services"
        BlockchainRPC["Blockchain RPC Endpoints"]:::external
        PythAPI["Pyth API"]:::external
        EmbeddingDocs["Embedding Docs Repository"]:::external
    end

    %% Connections from Frontend to Backend
    PageChat -->|"sends chat query"| AgentAPI
    ChatComponents -->|"renders chat"| PageChat
    BridgeUI -->|"initiates bridge"| Chains
    PageMain -->|"navigates to bridge"| BridgeUI
    PageNetwork -->|"navigates to bridge"| BridgeUI
    AgentHooks -->|"manages state"| AgentAPI
    Providers -->|"provides context"| AgentAPI

    %% Backend internal flows and External interactions
    RAGProvider -->|"retrieves pricing"| PythAPI
    AgentAPI -->|"may call"| EmbeddingAPI
    EmbeddingLogic -->|"retrieves docs"| EmbeddingDocs
    BridgeProvider -->|"executes on"| BlockchainRPC

    %% Styling
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef external fill:#FFE0B2,stroke:#E65100,stroke-width:2px;

    %% Click Events for Frontend
    click PageMain "https://github.com/javabridge/javabridge-next/blob/javabridge/app/page.jsx"
    click PageNetwork "https://github.com/javabridge/javabridge-next/blob/javabridge/app/network/page.jsx"
    click PageChat "https://github.com/javabridge/javabridge-next/blob/javabridge/app/chat/page.jsx"
    click BridgeUI "https://github.com/javabridge/javabridge-next/blob/javabridge/app/components/Bridge.jsx"
    click BridgeHandler "https://github.com/javabridge/javabridge-next/blob/javabridge/app/components/BridgeHandler.js"
    click MobileMenu "https://github.com/javabridge/javabridge-next/blob/javabridge/app/components/MobileMenu.jsx"
    click ChatComponents "https://github.com/javabridge/javabridge-next/tree/javabridge/app/chat/components"
    click ReusableUI "https://github.com/javabridge/javabridge-next/tree/javabridge/components/ui"
    click AgentHooks "https://github.com/javabridge/javabridge-next/blob/javabridge/app/hooks/useAgent.ts"
    click Providers "https://github.com/javabridge/javabridge-next/blob/javabridge/app/providers.jsx"

    %% Click Events for API & Backend
    click AgentAPI "https://github.com/javabridge/javabridge-next/tree/javabridge/app/api/agent"
    click EmbeddingAPI "https://github.com/javabridge/javabridge-next/tree/javabridge/app/api/embedding"
    click Chains "https://github.com/javabridge/javabridge-next/blob/javabridge/lib/chains.js"
    click Contracts "https://github.com/javabridge/javabridge-next/blob/javabridge/lib/contracts.js"
    click Web3Call "https://github.com/javabridge/javabridge-next/blob/javabridge/lib/web3-call.js"
    click BridgeProvider "https://github.com/javabridge/javabridge-next/tree/javabridge/lib/action-providers/bridge"
    click RAGProvider "https://github.com/javabridge/javabridge-next/tree/javabridge/lib/action-providers/rag"
    click EmbeddingLogic "https://github.com/javabridge/javabridge-next/blob/javabridge/lib/embedding.js"

    %% Click Event for External Docs
    click EmbeddingDocs "https://github.com/javabridge/javabridge-next/tree/javabridge/embedding_docs"
```
