# 0xoucan/celo-mind-dn architecture

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

- Interactive diagram: https://gitdiagram.com/0xoucan/celo-mind-dn
- Repository: https://github.com/0xoucan/celo-mind-dn

## Overview

##### Layers
Layer 1 – External Interfaces (How users & frontends interact)
Layer 2 – Core Backend (Agent orchestration & action providers)
Layer 3 – Infrastructure & External Services (Blockchain, AI, wallets)

##### Main Components per Layer

Layer 1: External Interfaces
- CLI Chatbot (src/chatbot.ts)
- Telegram Bot Interface (src/telegram-interface.ts)
- Web UI (external repo) ↔ API Server (src/api-server.ts)

Layer 2: Core Backend
- Agent Orchestrator
– Receives natural-language commands
– Routes to action providers
- Action Providers (src/action-providers/*)
– Aave, ICHI vault, Mento swap, Balance-checker modules
– Each exposes a unified “executeAction” interface
- Network Module (src/network/network.ts)
– RPC client to Celo nodes
- Utilities & Helpers
– Logger (src/utils/logger.ts)
– Rate limiter (src/utils/rate-limiter.ts)
– Transaction utils (src/utils/transaction-utils.ts)
- Constants & Types (src/constants, src/types)

Layer 3: Infrastructure & External Services
- Celo Blockchain (RPC)
- OpenAI API (AI agent)
- Browser Wallet (MetaMask, Rabby)
- Telegram API
- Redis or in-memory cache (agent caching)

##### Relationships & Data Flow
1. User/Frontend → Interface Layer
– CLI or Telegram bot or Web UI sends command
2. Interface → API Server / Chatbot process
3. API Server invokes Agent Orchestrator
4. Orchestrator → Appropriate Action Provider
5. Action Provider → Network Module → Celo RPC
6. Celo RPC → Blockchain → transaction result
7. Result streams back up → Interface → User
8. Throughout:
– OpenAI API calls for command parsing/strategy
– Rate limiter and logger wrap all requests

##### Architectural Patterns & Principles
- Modular “plugin” pattern for action providers
- Layered separation: Interfaces ↔ Business Logic ↔ Infrastructure
- Single responsibility: utilities, constants, network all isolated
- Streaming responses & caching for performance

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: External Interfaces
    subgraph "External Interfaces"
        CLI["CLI Chatbot"]:::frontend
        TEL["Telegram Interface"]:::frontend
        WEB["Web UI"]:::frontend
        API["API Server (Express)"]:::frontend
    end

    %% Layer 2: Core Backend
    subgraph "Core Backend"
        ORCH["Agent Orchestrator"]:::backend
        subgraph "Action Providers"
            AAVE["Aave"]:::backend
            ICHI["ICHI Vault"]:::backend
            MENTO["Mento Swap"]:::backend
            BAL["Balance Checker"]:::backend
        end
        NET["Network Module"]:::backend
        LOGGER["Logger"]:::backend
        RATE["Rate Limiter"]:::backend
    end

    %% Layer 3: Infrastructure & External Services
    subgraph "Infrastructure & External Services"
        CEL["Celo Blockchain"]:::infra
        OPENAI["OpenAI API"]:::infra
        WLET["Browser Wallet"]:::infra
        TELEAPI["Telegram API"]:::infra
        CACHE["Cache (Redis)"]:::infra
    end

    %% Connections
    CLI -->|"Chat msg"| ORCH
    TEL -->|"Telegram msg"| ORCH
    WEB -->|"REST"| API
    API -->|"internal REST"| ORCH

    ORCH -->|"executeAction"| AAVE
    ORCH -->|"executeAction"| ICHI
    ORCH -->|"executeAction"| MENTO
    ORCH -->|"executeAction"| BAL

    AAVE -->|"RPC"| NET
    ICHI -->|"RPC"| NET
    MENTO -->|"RPC"| NET
    BAL -->|"RPC"| NET

    NET -->|"JSON-RPC"| CEL
    ORCH -->|"strategy"| OPENAI

    CLI -->|"logs/metrics"| LOGGER
    TEL -->|"logs/metrics"| LOGGER
    API -->|"logs/metrics"| LOGGER
    ORCH -->|"logs/metrics"| LOGGER

    CLI -->|"rate limit"| RATE
    TEL -->|"rate limit"| RATE
    API -->|"rate limit"| RATE
    ORCH -->|"rate limit"| RATE

    TEL -->|"API calls"| TELEAPI
    ORCH -->|"cache lookup"| CACHE
    ORCH -->|"cache store"| CACHE
    ORCH -->|"wallet sign"| WLET

    %% Click Events
    click CLI "https://github.com/0xoucan/celo-mind-dn/blob/main/src/chatbot.ts"
    click TEL "https://github.com/0xoucan/celo-mind-dn/blob/main/src/telegram-interface.ts"
    click API "https://github.com/0xoucan/celo-mind-dn/blob/main/src/api-server.ts"
    click ORCH "https://github.com/0xoucan/celo-mind-dn/blob/main/src/api-server.ts"
    click AAVE "https://github.com/0xoucan/celo-mind-dn/tree/main/src/action-providers/aave"
    click ICHI "https://github.com/0xoucan/celo-mind-dn/tree/main/src/action-providers/ichi-vault"
    click MENTO "https://github.com/0xoucan/celo-mind-dn/tree/main/src/action-providers/mento-swap"
    click BAL "https://github.com/0xoucan/celo-mind-dn/tree/main/src/action-providers/balance-checker"
    click NET "https://github.com/0xoucan/celo-mind-dn/blob/main/src/network/network.ts"
    click LOGGER "https://github.com/0xoucan/celo-mind-dn/blob/main/src/utils/logger.ts"
    click RATE "https://github.com/0xoucan/celo-mind-dn/blob/main/src/utils/rate-limiter.ts"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0066CC,color:#003366
    classDef backend fill:#E6FFE6,stroke:#339933,color:#004D00
    classDef infra fill:#FFE6CC,stroke:#CC6600,color:#663300
```
