# telefragged/off-the-grid architecture

> Architecture diagram of the GitHub repository telefragged/off-the-grid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/telefragged/off-the-grid
- Repository: https://github.com/telefragged/off-the-grid

## Overview

##### Project type and purpose
- Off the Grid is a Rust-based, multi-crate CLI application plus an off-chain matching service that interacts with the Ergo blockchain.
- Its purpose is to enable users to create, view, redeem, and automatically match “grid trading” orders via a deployed smart contract (grid_multi), while using an Ergo node HTTP API and an external AMM (Spectrum).

##### File structure
- Root workspace (Cargo.toml, Cargo.lock, flake.nix, Nix, GitHub workflows)
- contracts/grid_multi – on-chain contract source and compiled symbols
- cli/ – main Rust binary crate “off-the-grid”:
- src/main.rs – entry point routing subcommands
- src/commands/… – grid, matcher, scans, tokens, error handling
- src/node/… – HTTP client for node RPC: scan, transactions, wallet, client config
- matcher_config.json, node_config.json, scan_config.json – configuration for matching bot, node connection, scan IDs
- cli/tests – integration/regression tests
- config files & Nix define build and run environments

##### README for additional insights
- Describes on-chain contract usage, off-chain bots, supported sources (Spectrum), and CLI commands
- Emphasizes two runtime components: the CLI (user-driven) and the matcher bot (automated order matching)

a. Main components
- User (CLI) – issues commands
- off-the-grid binary – houses subcommands: grid, scans, tokens, matcher
- Ergo Node – exposes HTTP RPC (scan UTXOs, wallet, mempool, broadcast tx)
- Blockchain – on-chain state and deployed grid_multi contract
- Spectrum AMM – external liquidity source via Explorer API
- Configuration Store – node_config.json, matcher_config.json, scan_config.json
b. Relationships & interactions
- CLI → Node:
– scans UTXOs (to find existing grid orders, wallet state)
– builds and broadcasts transactions (create/redeem/match orders)
- CLI → Explorer API: fetch token metadata (tokens update command)
- Matcher → Spectrum AMM: fetch current pool prices/reserves to determine match conditions
- Node ↔ Blockchain: maintain UTXOs, execute contract logic when txs are included
- On-chain Contract: enforces correct order matching or owner signature
c. Architectural patterns & design principles
– Separation of on-chain vs off-chain concerns
– Config-driven behavior: decouples deployment details from code
– Single binary with subcommands pattern for different roles (user CLI vs matcher bot)
d. Key technologies & frameworks
– Rust / Cargo / Nix (build environment)
– Ergo node HTTP RPC API
– Ergo contracts written in Sigmastate (contract.es)
– Spectrum AMM Explorer API
– Proptest for regression tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Off-chain CLI component
    subgraph "off-the-grid CLI"  
        direction TB
        CLI_Main["main.rs"]:::offchain
        CLI_Crate["Cargo.toml"]:::offchain
        subgraph "Commands"  
            direction TB
            Grid_Mod["grid/mod.rs"]:::offchain
            Grid_Create["create.rs"]:::offchain
            Grid_Redeem["redeem.rs"]:::offchain
            Grid_Sub["subcommands.rs"]:::offchain
            Matcher_Cmd["matcher.rs"]:::offchain
            Scans_Cmd["scans.rs"]:::offchain
            Tokens_Cmd["tokens.rs"]:::offchain
        end
        subgraph "Domain Boxes"
            direction TB
            Boxes_Mod["boxes/mod.rs"]:::offchain
            Liquidity_Box["liquidity_box.rs"]:::offchain
            Tracked_Box["tracked_box.rs"]:::offchain
            Wallet_Box["wallet_box.rs"]:::offchain
            Describe_Box["describe_box.rs"]:::offchain
        end
        subgraph "Node HTTP Client"
            direction TB
            Node_Mod["node/mod.rs"]:::offchain
            Client_RS["client.rs"]:::offchain
            Scan_RS["scan.rs"]:::offchain
            Tx_RS["transactions.rs"]:::offchain
            Wallet_RS["wallet.rs"]:::offchain
        end
        subgraph "Spectrum AMM Integration"
            direction TB
            Spectrum_Mod["spectrum/mod.rs"]:::offchain
            Pool_RS["pool.rs"]:::offchain
        end
        subgraph "Config Modules"
            direction TB
            Matcher_Config["matcher_config.rs"]:::config
            Node_Config["node_config.rs"]:::config
            Scan_Config["scan_config.rs"]:::config
        end
    end

    %% Configuration files
    subgraph "Config Files"
        direction TB
        Matcher_JSON["matcher_config.json"]:::config
        Node_JSON["node_config.json"]:::config
        Scan_JSON["scan_config.json"]:::config
    end

    %% External Services
    Spectrum_API["Spectrum AMM API"]:::external

    %% Node and Blockchain
    NodeRPC["Ergo Node RPC"]:::node
    Blockchain["Blockchain (grid_multi contract)"]:::chain
    Contract_Source["contract.es"]:::chain
    Contract_Symbols["symbols.json"]:::chain

    %% Tests
    Test_RS["test_multi.rs"]:::test

    %% Relationships
    User -->|uses| CLI_Main
    CLI_Main --> CLI_Crate
    CLI_Main --> Grid_Mod
    CLI_Main --> Matcher_Cmd
    CLI_Main --> Scans_Cmd
    CLI_Main --> Tokens_Cmd
    CLI_Main --> Boxes_Mod
    CLI_Main --> Node_Mod
    CLI_Main --> Spectrum_Mod
    CLI_Main --> Matcher_Config
    CLI_Main --> Node_Config
    CLI_Main --> Scan_Config

    CLI_Main -->|scan,broadcast| NodeRPC
    Grid_Mod -->|subcommands| Grid_Create
    Grid_Mod --> Grid_Redeem
    Grid_Mod --> Grid_Sub

    Scans_Cmd -->|UTXO scan| NodeRPC
    Tokens_Cmd -->|metadata fetch| Spectrum_API

    Matcher_Cmd -->|scan,broadcast| NodeRPC
    Matcher_Cmd -->|price fetch| Spectrum_API
    Matcher_Cmd --> Matcher_Config
    Matcher_Cmd --> Scan_Config
    Matcher_Cmd --> Node_Config

    NodeRPC -->|reads/writes| Blockchain
    Blockchain --> Contract_Source
    Blockchain --> Contract_Symbols

    %% Config files to CLI & Matcher
    Matcher_JSON --> CLI_Main
    Node_JSON --> CLI_Main
    Scan_JSON --> CLI_Main

    Matcher_JSON --> Matcher_Cmd
    Node_JSON --> Matcher_Cmd
    Scan_JSON --> Matcher_Cmd

    %% Tests node
    Test_RS --> CLI_Main

    %% Click Events
    click CLI_Main "https://github.com/telefragged/off-the-grid/blob/master/cli/src/main.rs"
    click CLI_Crate "https://github.com/telefragged/off-the-grid/blob/master/cli/Cargo.toml"
    click Grid_Mod "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/grid/mod.rs"
    click Grid_Create "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/grid/create.rs"
    click Grid_Redeem "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/grid/redeem.rs"
    click Grid_Sub "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/grid/subcommands.rs"
    click Matcher_Cmd "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/matcher.rs"
    click Scans_Cmd "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/scans.rs"
    click Tokens_Cmd "https://github.com/telefragged/off-the-grid/blob/master/cli/src/commands/tokens.rs"
    click Boxes_Mod "https://github.com/telefragged/off-the-grid/blob/master/cli/src/boxes/mod.rs"
    click Liquidity_Box "https://github.com/telefragged/off-the-grid/blob/master/cli/src/boxes/liquidity_box.rs"
    click Tracked_Box "https://github.com/telefragged/off-the-grid/blob/master/cli/src/boxes/tracked_box.rs"
    click Wallet_Box "https://github.com/telefragged/off-the-grid/blob/master/cli/src/boxes/wallet_box.rs"
    click Describe_Box "https://github.com/telefragged/off-the-grid/blob/master/cli/src/boxes/describe_box.rs"
    click Node_Mod "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node/mod.rs"
    click Client_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node/client.rs"
    click Scan_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node/scan.rs"
    click Tx_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node/transactions.rs"
    click Wallet_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node/wallet.rs"
    click Spectrum_Mod "https://github.com/telefragged/off-the-grid/blob/master/cli/src/spectrum/mod.rs"
    click Pool_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/src/spectrum/pool.rs"
    click Matcher_Config "https://github.com/telefragged/off-the-grid/blob/master/cli/src/matcher_config.rs"
    click Node_Config "https://github.com/telefragged/off-the-grid/blob/master/cli/src/node_config.rs"
    click Scan_Config "https://github.com/telefragged/off-the-grid/blob/master/cli/src/scan_config.rs"
    click Matcher_JSON "https://github.com/telefragged/off-the-grid/blob/master/matcher_config.json"
    click Node_JSON "https://github.com/telefragged/off-the-grid/blob/master/node_config.json"
    click Scan_JSON "https://github.com/telefragged/off-the-grid/blob/master/scan_config.json"
    click Contract_Source "https://github.com/telefragged/off-the-grid/blob/master/contracts/grid_multi/contract.es"
    click Contract_Symbols "https://github.com/telefragged/off-the-grid/blob/master/contracts/grid_multi/symbols.json"
    click Test_RS "https://github.com/telefragged/off-the-grid/blob/master/cli/tests/test_multi.rs"

    %% Styles
    classDef offchain fill:#cce5ff,stroke:#004085,color:#004085;
    classDef node fill:#ffe5b4,stroke:#805000,color:#805000;
    classDef chain fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef test fill:#fff3cd,stroke:#856404,color:#856404;
```
