# 0xoucan/nilaiagent architecture

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

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

## Overview

##### Main Components
- Chatbot Engine & Interface:
- Central chatbot logic (src/chatbot.ts) and the Telegram interface integration (src/telegram-interface.ts). These components serve as the front door for user interactions.
- Action Providers:
- Different action providers by their functionality:
- NIL Account Actions (src/action-providers/nil-account): Manages balance checks and smart account operations.
- NIL Contract Actions (src/action-providers/nil-contract): Deals with deploying and interacting with various smart contract types.
- NIL Supply Chain Actions (src/action-providers/nil-supply-chain): Specifically handles the supply chain contracts, ensuring proper deployment order and interactions between Manufacturer and Retailer.
- Script Modules:
- Scripts (located in src/scripts) as components handling command execution for contract deployment and interactions. They are the bridge between the user commands (from the chatbot) and the blockchain operations.
- External Services & Configurations:
- Connections to external blockchain endpoints (NIL_RPC_ENDPOINT, NIL_FAUCET_ENDPOINT), the Cometa service for contract compilation/verification, and environment configurations.
- Optionally, note OpenAI API integration via the OPENAI_API_KEY if it plays a role in the assistant’s conversation features.

##### Relationships and Interactions
- User Input to Interfaces:
- How users interact with either Chat Mode or Telegram Mode, which then route commands to the Chatbot Engine.
- Chatbot Engine Workflow:
- How the chatbot engine parses commands, then dispatches requests to the appropriate Action Provider based on the operation (e.g., deploying a contract, checking balances, managing accounts, or executing supply chain orders).
- Action Providers Interaction:
- Within each module (nil-account, nil-contract, nil-supply-chain), indicate the separation of concerns such as schema validation, error handling, and specific business logic for each blockchain operation.
- Scripts and External Connections:
- Script modules that can execute commands like “deploy-counter” or “interact-supply-chain” which then use the lower-level action provider interfaces.
- External connections like NIL Blockchain (via RPC and Faucet endpoints) and Cometa for tasks like compilation and contract verification.

##### Architectural Patterns and Technologies
- Modular Design:
- That the project is designed in a modular fashion by separating actions into distinct providers, each encapsulating specific blockchain functionality.
- Command Pattern:
- That the chatbot processes various commands which are mapped to underlying contract deployment and interaction functionalities.
- External Integrations:
- How integration with external blockchain services, environment configurations, and possibly OpenAI APIs (given the chatbot context) play crucial roles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UCI("Chat Mode Interface"):::ui
        TI("Telegram Interface"):::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        CE("Chatbot Engine"):::business
    end

    %% Action Providers Layer
    subgraph "Action Providers Layer"
        NAA("NIL Account Action Provider"):::action
        NAC("NIL Contract Action Provider"):::action
        NAS("NIL Supply Chain Action Provider"):::action
    end

    %% Script Modules Layer
    subgraph "Script Modules Layer"
        DCS("Deploy Counter Script"):::script
        DSCS("Deploy Supply Chain Script"):::script
        ICS("Interact Counter Script"):::script
        ISCS("Interact Supply Chain Script"):::script
        CSS("Compile Supply Chain Script"):::script
    end

    %% External Services & Configurations
    subgraph "External Services & Configurations"
        NB("NIL Blockchain Endpoints"):::ext
        CS("Cometa Service"):::ext
        EC("Environment Config"):::ext
    end

    %% Connections from User Interfaces to Chatbot Engine
    UCI -->|"sends command"| CE
    TI  -->|"sends command"| CE

    %% Chatbot Engine dispatches to Action Providers
    CE -->|"balance/deploy/account"| NAA
    CE -->|"deploy/interact/contract"| NAC
    CE -->|"supply chain tasks"| NAS

    %% Chatbot Engine calls Script Modules for command execution
    CE -->|"execute script"| DCS
    CE -->|"execute script"| DSCS
    CE -->|"execute script"| ICS
    CE -->|"execute script"| ISCS
    CE -->|"execute script"| CSS

    %% Action Providers interact with External Services
    NAA -->|"query blockchain"| NB
    NAC -->|"query blockchain"| NB
    NAS -->|"query blockchain"| NB

    %% Script Modules connect to External Services
    DCS -->|"trigger blockchain operation"| NB
    DSCS -->|"trigger blockchain operation"| NB
    ICS -->|"trigger blockchain operation"| NB
    ISCS -->|"trigger blockchain operation"| NB
    CSS -->|"trigger blockchain operation"| NB

    %% External Config feeds into both Chatbot and Providers
    EC ---|"configures endpoints"| CE
    EC ---|"configures endpoints"| NAA
    EC ---|"configures endpoints"| NAC
    EC ---|"configures endpoints"| NAS

    %% Click Events
    click CE "https://github.com/0xoucan/nilaiagent/blob/main/src/chatbot.ts"
    click TI "https://github.com/0xoucan/nilaiagent/blob/main/src/telegram-interface.ts"
    click NAA "https://github.com/0xoucan/nilaiagent/tree/main/src/action-providers/nil-account"
    click NAC "https://github.com/0xoucan/nilaiagent/tree/main/src/action-providers/nil-contract"
    click NAS "https://github.com/0xoucan/nilaiagent/tree/main/src/action-providers/nil-supply-chain"
    click DCS "https://github.com/0xoucan/nilaiagent/blob/main/src/scripts/deploy-counter.ts"
    click DSCS "https://github.com/0xoucan/nilaiagent/blob/main/src/scripts/deploy-supply-chain.ts"
    click ICS "https://github.com/0xoucan/nilaiagent/blob/main/src/scripts/interact-counter.ts"
    click ISCS "https://github.com/0xoucan/nilaiagent/blob/main/src/scripts/interact-supply-chain.ts"
    click CSS "https://github.com/0xoucan/nilaiagent/blob/main/src/scripts/compile-supply-chain.ts"
    click EC "https://github.com/0xoucan/nilaiagent/blob/main/.env.example"

    %% Styles
    classDef ui fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef business fill:#A2D5F2,stroke:#333,stroke-width:2px;
    classDef action fill:#CDEAC0,stroke:#333,stroke-width:2px;
    classDef script fill:#F9D5E5,stroke:#333,stroke-width:2px;
    classDef ext fill:#D0E1F9,stroke:#333,stroke-width:2px;
```
