# forta-network/forta-bot-sdk architecture

> Architecture diagram of the GitHub repository forta-network/forta-bot-sdk, 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/forta-network/forta-bot-sdk
- Repository: https://github.com/forta-network/forta-bot-sdk

## Overview

##### Main components
- CLI Application: This component encapsulates all the commands (init, run, push, publish, enable/disable, keyfile, logs) that allow users to perform tasks from command line.
- SDK Libraries:
– Typescript/JavaScript SDK (in the “sdk” folder and “cli” modules that use it): Contains functionalities for interacting with blockchain events, alerts, and for managing bot configurations.
– Python SDK (in the “python-sdk” folder): Offers equivalent functionality for Python-based detection bots.
- Starter Projects: Sample projects organized by language (js, py, ts under the “starter-project” folder) that show how to use the SDK and CLI.
- Smart Contract Wrappers: Located under “cli/contracts”, these provide ABI files and helper functions to interact with deployed smart contracts (agent registry, staking contracts, etc.).
- Utility Modules and Test Suites: Utility functions (under “cli/utils” and related directories) perform common tasks (e.g., interacting with IPFS, fetching logs or blockchain data, decoding JWTs) and automate testing (test files across the project).
- CI/CD Pipeline: GitHub workflows under “.github/workflows” provide automated testing and continuous integration for both the CLI and SDK.

##### Relationships and data flows
- User Input (commands issued via the CLI) flows into the CLI Application component.
- The CLI commands then invoke underlying utility functions and methods from the SDK libraries.
- SDK functions communicate with external systems such as:
– Blockchain networks (using JSON-RPC via ethers.js/web3, or direct JSON-RPC calls),
– IPFS nodes (for uploading files or retrieving agent information),
– gRPC services (as indicated by the proto definitions and controllers in the CLI “run/server” folder).
- The smart contract wrappers are used by both the CLI and SDK to interact with blockchain contracts (for agent registration, staking, etc.).
- The Python SDK is parallel to the JS/TS SDK, exposing many equivalent functionalities, and also includes its own test and build pipelines.

##### Important architectural patterns/design principles
- Separation of Concerns: There is a clear separation between the CLI (user interface), the SDK libraries (business logic) and the starter projects (usage examples).
- Modularity: The project is structured into multiple well-defined modules (commands, contracts, utilities, SDK core) to enable easy extension and maintenance.
- Cross-Language Support: Two distinct SDKs (JavaScript/TypeScript and Python) indicate design considerations for supporting developers in different ecosystems.
- Test-Driven Development: The ample presence of unit tests and CI/CD pipelines shows that automated testing is integral to the design.

##### Detail relevant technologies and frameworks
- Node.js/TypeScript for the CLI and main SDK, along with test frameworks like Jest.
- Python (with pytest) for the Python-sdk.
- Ethers.js and/or web3 (for blockchain interactions).
- gRPC (as referenced in the “run/server” subdirectory that contains proto definitions).
- IPFS (for some storage and retrieval functionalities as shown by the “ipfs” utilities).
- GitHub Actions for CI/CD (using YAML workflows).

##### Detail without overcomplicating
- Annotations, if needed, to note design principles (modularity, separation of concerns) or protocol interactions (JSON-RPC, gRPC).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Input"
        U("User CLI Command"):::user
    end

    subgraph "CLI Layer"
        CLI("Forta Agent CLI"):::cli
        CM("CLI Commands (init,run,push,publish,stake,logs)"):::cliCmd
    end

    subgraph "SDK Layer"
        JSSDK("JS/TS SDK Library"):::sdk
        PySDK("Python SDK Library"):::sdk
    end

    subgraph "Smart Contract & Blockchain"
        Contracts("Smart Contract Wrappers"):::contract
    end

    subgraph "Utility & Testing"
        Utils("Utility Modules (IPFS,Polyscan,etc.)"):::utils
        CICD("CI/CD Pipeline"):::cicd
    end

    subgraph "Starter Projects"
        Starter("Starter Projects (JS,TS,Python)"):::starter
    end

    subgraph "External Services"
        RPC("Blockchain RPC Node (JSON-RPC)"):::external
        IPFS("IPFS Gateway"):::external
        gRPC("gRPC Server"):::external
    end

    U -->|"issuesCommand"| CLI
    CLI -->|"interpretsCommands"| CM

    CM -->|"invokesSDK"| JSSDK
    CM -->|"invokesSDK"| PySDK

    JSSDK -->|"callsContracts"| Contracts
    PySDK -->|"callsContracts"| Contracts

    JSSDK -->|"usesUtilities"| Utils
    PySDK -->|"usesUtilities"| Utils

    Utils -->|"fetchesData"| RPC
    Utils -->|"handlesStorage"| IPFS

    JSSDK -->|"communicatesWith"| gRPC
    PySDK -->|"communicatesWith"| gRPC

    CLI -->|"triggersTests"| CICD
    JSSDK -->|"triggersTests"| CICD
    PySDK -->|"triggersTests"| CICD

    Starter -->|"demonstratesCLIUsage"| CLI
    Starter -->|"demonstratesSDKUsage"| JSSDK
    Starter -->|"demonstratesSDKUsage"| PySDK

    %% Click Events
    click CLI "https://github.com/forta-network/forta-bot-sdk/tree/master/cli"
    click CM "https://github.com/forta-network/forta-bot-sdk/tree/master/cli/commands/"
    click JSSDK "https://github.com/forta-network/forta-bot-sdk/tree/master/sdk"
    click PySDK "https://github.com/forta-network/forta-bot-sdk/tree/master/python-sdk"
    click Contracts "https://github.com/forta-network/forta-bot-sdk/tree/master/cli/contracts"
    click Utils "https://github.com/forta-network/forta-bot-sdk/tree/master/cli/utils"
    click Starter "https://github.com/forta-network/forta-bot-sdk/tree/master/starter-project"
    click CICD "https://github.com/forta-network/forta-bot-sdk/tree/master/.github/workflows"

    %% Styles
    classDef cli fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef cliCmd fill:#90caf9,stroke:#1e88e5,stroke-width:2px;
    classDef sdk fill:#ffe082,stroke:#fb8c00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef contract fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef utils fill:#f8bbd0,stroke:#d81b60,stroke-width:2px;
    classDef cicd fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
    classDef starter fill:#dcedc8,stroke:#7cb342,stroke-width:2px;
    classDef external fill:#ffccbc,stroke:#e64a19,stroke-width:2px;
    classDef user fill:#e0f7fa,stroke:#00838f,stroke-width:2px;
```
