# cmalf/getgrass-bot-js architecture

> Architecture diagram of the GitHub repository cmalf/getgrass-bot-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cmalf/getgrass-bot-js
- Repository: https://github.com/cmalf/getgrass-bot-js

## Overview

##### Project Type and Purpose
- This is a Node.js–based command‑line bot (“getgrass‑miner‑bot‑js”) whose single purpose is to automate Grass Season 2 node mining by rotating through proxy servers and maintaining WebSocket connections to the getgrass.io API.
- It is not a multi‑service or full‑stack application, but rather a self‑contained CLI script with modular internal components.

##### File Structure Analysis
- Top‑level releases folders (SCRIPT‑V0.x, Extention‑Version‑v0.1) each bundle a version of the bot as a ZIP; only Extention‑Version‑v0.1 contains the actual source (`main.js`, `configuration.js`, `proxy.txt`, `package.json`).
- Key files under the active version:
- configuration.js – loads user settings (userId, mining parameters)
- proxy.txt – list of HTTP/SOCKS proxies to rotate through
- main.js – orchestrates startup, reads config, instantiates modules, runs the mining loop
- package.json – lists external libraries (WebSocket client, proxy agents, etc.)

##### README Insights
- Confirms:
- Modular handling of multiple IP addresses via proxies
- WebSocket management over HTTP/SOCKS protocols
- Single‑entry CLI interface (`npm start`)

##### Components and Their Relationships
1. CLI / Entry Point
2. Configuration Loader module
3. Proxy Manager module
4. WebSocket Client module
5. Bot Core Logic (mining loop, scheduling)
6. Data Processor / Response Handler
7. Logger / Metrics
8. External Services:
– getgrass.io WebSocket API (Grass Node)
– Proxy Providers (via addresses in proxy.txt)
- CLI → Configuration Loader: load userId, endpoints, proxy file path
- Configuration Loader → Bot Core: pass in settings
- Bot Core ↔ Proxy Manager: request “next proxy” for each connection
- Bot Core ↔ WebSocket Client: open/close/manage WS connections
- WebSocket Client ↔ External getgrass.io API: send/receive mining messages
- Data Processor ← WebSocket Client: parse incoming messages (rewards, errors)
- Data Processor → Bot Core: feed results back into scheduling logic
- Bot Core → Logger: write events, errors, mining metrics
- Proxy Manager ↔ proxy.txt (file): read/refresh proxy list
c. Architectural Patterns and Principles
- Separation of concerns: configuration, proxy management, networking (WS), business logic, logging
- Single‑process, event‑driven architecture based on Node.js event loop
- Extensibility point: swap in different proxy providers or proxy‐rotation strategies by swapping modules
d. Key Technologies and Libraries
- Node.js runtime
- “ws” (WebSocket client) or similar library
- “http‑proxy‑agent” / “socks‑proxy‑agent” for proxy support
- Native `fs` module for `proxy.txt` and `configuration.js`
- Any logging library (e.g., `winston`, if present)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "getgrass‑miner‑bot‑js Architecture"
        subgraph "Configuration Layer"
            CLI["CLI / Entry Point"]:::internal
            ConfigLoader["Configuration Loader"]:::internal
            ProxyFile["proxy.txt"]:::file
        end

        subgraph "Core Logic Layer"
            BotCore["Bot Core Logic"]:::internal
            DataProcessor["Data Processor / Response Handler"]:::internal
            ProxyMgr["Proxy Manager"]:::internal
        end

        subgraph "Networking Layer"
            WSClient["WebSocket Client"]:::internal
        end

        subgraph "Logging"
            Logger["Logger / Metrics"]:::internal
        end

        subgraph "Dependency Manifest"
            Package["package.json"]:::library
        end
    end

    subgraph "External Services"
        Getgrass[(getgrass.io WebSocket API)]:::external
        ProxyServers[(Proxy Providers)]:::external
    end

    %% Connections
    CLI -->|"loadConfig()"| ConfigLoader
    ConfigLoader -->|"config settings"| BotCore

    BotCore -->|"getNextProxy()"| ProxyMgr
    ProxyMgr -->|"readFileSync('proxy.txt')"| ProxyFile
    ProxyMgr -->|"returnProxy"| BotCore

    BotCore -->|"connectWS()"| WSClient
    BotCore -->|"closeWS()"| WSClient

    WSClient -->|"WebSocket over SOCKS5"| Getgrass
    WSClient -->|"onMessage()"| DataProcessor

    DataProcessor -->|"processResult()"| BotCore

    BotCore -->|"logEvent()"| Logger

    Package -->|"declares libs"| WSClient
    Package -->|"declares deps"| ProxyMgr
    Package -->|"declares deps"| Logger

    %% Click Events
    click CLI "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/main.js"
    click ConfigLoader "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/configuration.js"
    click ProxyFile "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/proxy.txt"
    click WSClient "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/main.js"
    click BotCore "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/main.js"
    click DataProcessor "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/main.js"
    click Logger "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/main.js"
    click Package "https://github.com/cmalf/getgrass-bot-js/blob/main/Extention-Version-v0.1/package.json"

    %% Styles
    classDef internal fill:#BBE1FA,stroke:#0C7BDC
    classDef external fill:#C8E6C9,stroke:#2E7D32
    classDef file fill:#ECEFF1,stroke:#455A64
    classDef library fill:#FFF3E0,stroke:#EF6C00
```
