# 0xoucan/agentexoc architecture

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

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

## Overview

##### Project Type and Purpose
- This project is a specialized chatbot designed to integrate with multiple decentralized finance (DeFi) protocols on Base networks.
- It supports different operating modes (Chat, Autonomous, and Telegram) and provides a range of token and lending operations.
- The design needs to capture protocol-specific logic (for example, for the Xocolatl and BOBC protocols) and the multiple operational interfaces.

##### Analyzing the File Structure
- The top-level directory includes configuration (e.g., .env.example, package.json), TypeScript configuration (tsconfig.json), and documentation (README.md).
- Under the src directory, the following key components can be identified:
- Core chatbot logic (src/chatbot.ts): Contains central orchestration and decision-making.
- Telegram Interface (src/telegram-interface.ts): Connects the chatbot to Telegram, providing one of the user interaction modes.
- Action Providers (src/action-providers/): This folder splits into subdirectories for each protocol integration (e.g., bobc-protocol and xocolatl), which include:
- Provider implementations (e.g., bobcProtocolActionProvider.ts, xocolatlActionProvider.ts)
- Schema definitions (schemas.ts), constants, and error handling modules.
- These folders and files denote a modular design where each protocol’s business logic is encapsulated within its own provider.

##### Extracted Architectural Insights from the README
- The README provides high-level descriptions of the supported operations, error handling, network configurations, and environment variables.
- It emphasizes key functionalities like token operations, lending operations, safety features, and distinct operating modes (chat, autonomous, Telegram).
- Multi-protocol support is central, meaning the action providers need to be integrated with a common chatbot core that appropriately forwards user commands based on the selected protocol and mode.

a. Main Components:
- User Interfaces:
- Chat Mode (CLI interaction)
- Autonomous Mode (Scheduled execution)
- Telegram Mode (via Telegram interface)
- Chatbot Core Engine:
- The central component orchestrating command processing, network validations, and interaction with specific protocols.
- Action Providers:
- Xocolatl Protocol Provider – Handles operations (deposit/withdraw, mint/burn tokens, etc.) for Base Mainnet.
- BOBC Protocol Provider – Handles operations (collateral management, mint/burn, monitoring health factor) for Base Sepolia.
- External Components:
- Blockchain Networks: Base Mainnet and Base Sepolia.
- External Lending Pools and token contract services.
- Environment Configuration: API keys, wallet secrets, and network IDs.

b. Relationships and Interactions:
- Users (or automated triggers) interact with the system through one of the UI components.
- The Chatbot Core receives commands and routes requests based on the operating mode to the appropriate action provider.
- Action Providers interact with the underlying DeFi protocols using network calls and smart contract interactions.
- All interactions include error handling and validation layers (network checks, balance validations, etc.), which should be depicted alongside the primary data flow.

c. Architectural Patterns and Design Principles:
- Modularity: Each protocol (action provider) is encapsulated in its own directory with clearly separated logic, constants, schemas, and error handlers.
- Separation of Concerns: Distinct layers for UI, core business logic, and protocol-specific operations.
- Extensibility: Clear guidelines in the README for adding or modifying providers indicate an architecture designed to be easily extendable.

d. Technologies and Frameworks:
- Node/TypeScript is implied by the presence of package.json and tsconfig.json.
- Integration with third-party services such as Telegram (via telegram-interface.ts) and likely external DeFi APIs.
- OpenAI integration as indicated by the OPENAI_API_KEY in the environment setup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Adapters
    subgraph "User Interfaces"
        CLI["Chat Mode (CLI)"]:::ui
        AUTO["Autonomous Mode"]:::ui
        TELEGRAM["Telegram Interface"]:::ui
    end

    %% Chatbot Core Engine
    CORE["Chatbot Core Engine"]:::core

    %% Action Providers
    subgraph "Action Providers"
        BOBC["BOBC Protocol Provider"]:::provider
        XOCO["Xocolatl Protocol Provider"]:::provider
    end

    %% External Components
    subgraph "External Components"
        MAINNET["Base Mainnet (Blockchain)"]:::external
        SEPONET["Base Sepolia (Blockchain)"]:::external
        EXTERNAL["External Lending Pools & Token Services"]:::external
    end

    %% Data Flow
    CLI -->|"send-command"| CORE
    AUTO -->|"trigger-command"| CORE
    TELEGRAM -->|"user-message"| CORE

    CORE -->|"routes-to"| BOBC
    CORE -->|"routes-to"| XOCO

    BOBC -->|"interacts-with"| SEPONET
    BOBC -->|"calls"| EXTERNAL

    XOCO -->|"interacts-with"| MAINNET
    XOCO -->|"calls"| EXTERNAL

    %% Response/Error Flow
    BOBC -- "error/response" --> CORE
    XOCO -- "error/response" --> CORE
    CORE -- "reply" --> TELEGRAM
    CORE -- "reply" --> CLI
    CORE -- "reply" --> AUTO

    %% Click Events
    click CORE "https://github.com/0xoucan/agentexoc/blob/main/src/chatbot.ts"
    click TELEGRAM "https://github.com/0xoucan/agentexoc/blob/main/src/telegram-interface.ts"
    click BOBC "https://github.com/0xoucan/agentexoc/blob/main/src/action-providers/bobc-protocol/bobcProtocolActionProvider.ts"
    click XOCO "https://github.com/0xoucan/agentexoc/blob/main/src/action-providers/xocolatl/xocolatlActionProvider.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef provider fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
