# 0xoucan/sonicdeltamasterai architecture

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

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

## Overview

##### Main Components
- Input Interfaces:
- Chat Interface (chatbot.ts) used for interactive command inputs.
- Telegram Interface (telegram-interface.ts) for mobile and messaging-based commands.
- Command Processing/Dispatcher:
- This is the central engine that interprets commands (e.g., “delta-neutral-apy” or “execute-delta-neutral 10”) and routes them appropriately.
- Strategy Action Providers:
- Multiple modules under src/action-providers (e.g., aave-supply, delta-neutral, machfi, swrapper, usdce-swapx-beefy, wsswapx-beefy, etc.).
- Each provider contains its business logic and integration points with specific DeFi protocols.
- Strategy Manager:
- A module that may coordinate between different providers to balance portfolio management, execute risk checks, or choose the best yield optimization method.
- External Services and Blockchain Integrations:
- Connections to external protocols/services like Aave, MachFi, Beefy, and potentially SonicScan.
- Token Operations & Balance Checker:
- Modules that handle ERC20 token operations (wrapping, unwrapping, transfers) and portfolio balance validations.

##### Relationships and Flow
- Incoming requests (via chat or Telegram) are first processed by the Input Layer.
- The command is then sent to the Dispatcher / Command Processing unit.
- The Dispatcher evaluates the command and decides which Action Provider to invoke.
- E.g., a “delta-neutral-apy” command is routed to the corresponding provider that implements either the Aave- or MachFi-based delta neutral strategy.
- The selected Action Provider executes its internal process:
- Reads configuration data, applies strategy-specific constants, and uses inbuilt error handling.
- For strategies involving sequential actions (supply/collateral, borrow, wrap tokens, deploy into vaults), illustrate the command as a flow:
- Start → Supply collateral → Borrow asset → Token wrapping (if required) → Vault deposit → Yield calculation.
- Results and feedback are then returned to the interface (chat/telegram) as a processed response.

##### Architectural Patterns and Design Principles
- Modularity: The model employs a modular design where each action provider encapsulates distinct strategy logic.
- Flow-Oriented Execution: The system is command-driven – a user issues a command and a clear, sequential flow of execution is triggered.
- Separation of Concerns: Clear separation is evident between the presentation layer (chat/telegram interfaces), the business logic (action providers for strategies), and integrations with external protocols.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Interfaces
    subgraph "Input Interfaces"
        CI["Chat Interface"]:::interface
        TI["Telegram Interface"]:::interface
    end

    %% Core Processing
    subgraph "Core Processing"
        CD["Command Dispatcher"]:::dispatcher

        %% Action Providers
        subgraph "Action Providers"
            ASP["Aave Supply Provider"]:::provider
            BCP["Balance Checker Provider"]:::provider
            DNP["Delta Neutral Provider"]:::provider
            MSP["MachFi Strategy Provider"]:::provider
            BFP["Beefy Portfolio Provider"]:::provider
            SWP["SWrapper Provider"]:::provider
            USDCP["USDCE SwapX Beefy Provider"]:::provider
            WSP["WSSwapX Beefy Provider"]:::provider
            SMP["Strategy Manager"]:::provider
        end

        %% Provider Execution Flow (Generic Example)
        subgraph "Provider Execution Flow"
            START(("Start"))
            SC["Supply Collateral"]
            BA["Borrow Asset"]
            WT["Wrap Tokens"]
            VD["Vault Deposit"]
            YC["Yield Calculation"]
            RESULT(("Result"))
        end
    end

    %% External Integrations
    subgraph "External Services"
        Aave["Aave Service"]:::external
        MachFi["MachFi Service"]:::external
        Beefy["Beefy Service"]:::external
        ERC20["ERC20/Token Ops"]:::external
    end

    %% Flow Connections for Input and Processing
    CI -->|"command"| CD
    TI -->|"command"| CD

    CD -->|"routesTo"| ASP
    CD -->|"routesTo"| BCP
    CD -->|"routesTo"| DNP
    CD -->|"routesTo"| MSP
    CD -->|"routesTo"| BFP
    CD -->|"routesTo"| SWP
    CD -->|"routesTo"| USDCP
    CD -->|"routesTo"| WSP
    CD -->|"routesTo"| SMP

    %% Flow Connections for a Generic Provider Execution Example
    ASP -->|"executes"| START
    START -->|"step1"| SC
    SC -->|"step2"| BA
    BA -->|"step3"| WT
    WT -->|"step4"| VD
    VD -->|"step5"| YC
    YC -->|"finished"| RESULT

    %% Returning result to Interfaces (applies to any provider)
    RESULT -->|"return"| CI
    RESULT -->|"return"| TI

    %% External Integrations per Provider
    ASP ---|"integrates"| Aave
    MSP ---|"integrates"| MachFi
    BFP ---|"integrates"| Beefy
    BCP ---|"checks"| ERC20
    DNP ---|"couldIntegrate"| Aave
    SWP ---|"couldIntegrate"| ERC20
    USDCP ---|"couldIntegrate"| Beefy
    WSP ---|"couldIntegrate"| Beefy
    SMP ---|"coordinates"| ASP
    SMP ---|"coordinates"| DNP
    SMP ---|"coordinates"| MSP

    %% Click Events
    click CI "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/chatbot.ts"
    click TI "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/telegram-interface.ts"
    click CD "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/index.ts"
    click ASP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/aave-supply/aaveSupplyActionProvider.ts"
    click BCP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/balance-checker/balanceCheckerActionProvider.ts"
    click DNP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/delta-neutral/deltaNeutralActionProvider.ts"
    click MSP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/machfi/machfiActionProvider.ts"
    click BFP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/beefy-portfolio/beefyPortfolioActionProvider.ts"
    click SWP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/swrapper/sWrapperActionProvider.ts"
    click USDCP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/usdce-swapx-beefy/usdceSwapXBeefyActionProvider.ts"
    click WSP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/wsswapx-beefy/wsSwapXBeefyActionProvider.ts"
    click SMP "https://github.com/0xoucan/sonicdeltamasterai/blob/main/src/action-providers/strategy-manager/strategyManagerActionProvider.ts"

    %% Styles
    classDef interface fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef dispatcher fill:#cccccc,stroke:#333,stroke-width:2px;
    classDef provider fill:#b3b3b3,stroke:#333,stroke-width:2px;
    classDef external fill:#999999,stroke:#333,stroke-width:2px, font-style:italic;
    classDef execution fill:#d9d9d9,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;
    
    %% Apply execution class to provider flow nodes
    class START,SC,BA,WT,VD,YC,RESULT execution;
    
    %% Arrow styling (using gray tone)
    linkStyle default stroke:#666666,stroke-width:1.5px;
```
