# nfttoolz/blurbiddingbot architecture

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

- Interactive diagram: https://gitdiagram.com/nfttoolz/blurbiddingbot
- Repository: https://github.com/nfttoolz/blurbiddingbot

## Overview

##### Project Type & Purpose
- This is a Node.js CLI tool written in TypeScript that automates bidding on NFT collections on the Blur marketplace.
- Its primary function is to fetch collection data, evaluate pool sizes and bidding criteria, place or cancel bids via Blur’s API, and persist state/configuration locally.

##### File‐Structure Analysis
Top‐level
- package.json, tsconfig.json – Node/TypeScript config
- sample.env – environment variables template
- src/index.ts – CLI entrypoint
- src/commands/ – command definitions (run, cancel, collections, generateCollectionConfigs)
- src/actions/ – business logic “actions” invoked by each command
- src/blur/ – API client wrappers for Blur REST endpoints and (missing) WS socket
- src/os/ – “operating‐system” helpers mapping higher‐level operations (login, collectionBid, user)
- src/storage/ – file‐based persistence (CSV generation, configs, bids, wallets)
- src/store/ – in‐memory state slices (Redux‐style) for collections and wallets
- src/utils/ – HTTP (axios), blockchain provider, Discord notifications, rate-limiting, logging, feature flags

##### Core Components
A. CLI Interface
- index.ts invokes a command parser that reads process.argv and dispatches to the appropriate command module.
B. Command Layer (src/commands)
- Thin adapters that call a named “action” (e.g. run → portfolioCheck + bid loops).
C. Action Layer (src/actions)
- Encapsulates bidding logic, failsafe checks, state recovery, health checks, etc.
- Coordinates multiple services: Blur client, OS helpers, storage, store.
D. Blur API Client (src/blur)
- REST calls: bids, collections, healthCheck. (Plus private WS client in premium version.)
E. OS Helpers (src/os)
- High‐level operations like login(), fetch user data, place collection bids.
F. State Management (src/store)
- Redux‐style slices manage runtime state of collections and wallets.
G. Persistence (src/storage)
- Reads/writes JSON/CSV to disk (TMP_DIR) for configs, bids, wallet balances.
H. Utilities (src/utils)
- HTTP wrapper (axios), provider factory (ethers.js), Discord webhook notifier, rate limiter, logger.
I. External Systems
- Blur REST API & (private) WebSocket
- Ethereum RPC node (via provider)
- Discord API
- Local filesystem

##### Relationships & Data Flows
1. User runs `node dist/index.js [action]` → CLI Interface
2. CLI calls Command Layer → invokes corresponding Action
3. Action layer:
- Loads config from environment (sample.env → .env)
- Initializes store, storage, utils (provider, logger, rateLimit)
- Calls OS helpers & Blur client to retrieve pool data, user balance
- Applies bidding logic (consts + flags)
- Places/cancels bids via Blur client or OS helper
- Persists results to storage and updates in‐memory store
- Optionally sends Discord notifications
4. Underlying HTTP/RPC calls happen through utils/axios and utils/provider

##### Architectural Patterns & Design Principles
- Layered architecture: CLI → Command → Action → Service → Data
- Separation of concerns:
- Commands only route to actions
- Actions contain business logic
- API wrappers isolated in src/blur & src/os
- State vs. persistence decoupled (store vs. storage)
- Reusable utilities for cross‐cutting concerns
- Environment‐driven configuration (.env)
- Redux‐style in‐memory store for predictable state updates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::core
    end

    %% Command Layer
    subgraph "Command Layer"
        Run["run.ts"]:::core
        Cancel["cancel.ts"]:::core
        CollectionsCmd["collections.ts"]:::core
        GenConfig["generateCollectionConfigs.ts"]:::core
    end

    %% Action Layer
    subgraph "Action Layer"
        CollectionAct["collection.ts"]:::core
        FailsafeAct["failsafe.ts"]:::core
        PortfolioCheck["portfolioCheck.ts"]:::core
        RecoverState["recoverState.ts"]:::core
    end

    %% Service Layer
    subgraph "Service Layer"
        subgraph "Blur API Client"
            Bids["bids.ts"]:::service
            CollectionsAPI["collections.ts"]:::service
            Health["healthCheck.ts"]:::service
        end
        subgraph "OS Helpers"
            CollectionBid["collectionBid.ts"]:::service
            Login["login.ts"]:::service
            UserHelper["user.ts"]:::service
        end
    end

    %% State & Persistence
    subgraph "State & Persistence"
        subgraph "State Management"
            CollSlice["collectionsSlice.ts"]:::data
            WalletSlice["walletsSlice.ts"]:::data
            StoreIndex["index.ts"]:::data
        end
        subgraph "Persistence"
            StorageColl["collections.ts"]:::data
            ConfigStorage["collectionsConfig.ts"]:::data
            MyBidsStorage["myBids.ts"]:::data
            SuitableStorage["suitableCollections.ts"]:::data
            WalletStorage["wallets.ts"]:::data
        end
    end

    %% Utilities
    subgraph "Utilities"
        Axios["axios.ts"]:::utils
        Discord["discord.ts"]:::utils
        Flags["flags.ts"]:::utils
        Log["log.ts"]:::utils
        Provider["provider.ts"]:::utils
        Quantity["quantity.ts"]:::utils
        RateLimit["rateLimit.ts"]:::utils
    end

    %% External Systems
    subgraph "External"
        CloudBlur["Blur REST API"]:::external
        CloudWS["Blur WebSocket"]:::external
        EthNode["Ethereum RPC Node"]:::external
        DiscordAPI["Discord API"]:::external
        FileSystem["Local Filesystem"]:::external
    end

    %% Connections
    CLI --> Run
    CLI --> Cancel
    CLI --> CollectionsCmd
    CLI --> GenConfig

    Run --> PortfolioCheck
    Cancel --> FailsafeAct
    CollectionsCmd --> CollectionAct
    GenConfig --> RecoverState

    %% Actions to Services
    PortfolioCheck --> CollectionsAPI
    PortfolioCheck --> Bids
    PortfolioCheck --> CollectionBid
    FailsafeAct --> Bids
    FailsafeAct --> CollectionBid
    CollectionAct --> CollectionsAPI
    CollectionAct --> CollectionBid
    RecoverState --> Health
    RecoverState --> Login
    RecoverState --> UserHelper

    %% Actions to State & Persistence
    PortfolioCheck --> CollSlice
    PortfolioCheck --> StorageColl
    FailsafeAct --> WalletSlice
    FailsafeAct --> MyBidsStorage
    CollectionAct --> SuitableStorage
    RecoverState --> ConfigStorage
    RecoverState --> WalletStorage

    %% Actions to Utilities
    PortfolioCheck --> Axios
    PortfolioCheck --> Provider
    PortfolioCheck --> RateLimit
    PortfolioCheck --> Log
    PortfolioCheck --> Flags
    PortfolioCheck --> Discord
    FailsafeAct --> Log
    CollectionAct --> Flags
    RecoverState --> Log

    %% Service to External
    Bids --> CloudBlur
    CollectionsAPI --> CloudBlur
    Health --> CloudBlur
    CollectionBid --> CloudBlur
    Login --> CloudBlur
    UserHelper --> CloudBlur
    CollectionBid --> CloudWS
    Provider --> EthNode
    Discord --> DiscordAPI
    StorageColl --> FileSystem
    ConfigStorage --> FileSystem
    MyBidsStorage --> FileSystem
    SuitableStorage --> FileSystem
    WalletStorage --> FileSystem

    %% Click Events
    click CLI "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/index.ts"

    click Run "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/commands/run.ts"
    click Cancel "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/commands/cancel.ts"
    click CollectionsCmd "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/commands/collections.ts"
    click GenConfig "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/commands/generateCollectionConfigs.ts"

    click CollectionAct "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/actions/collection.ts"
    click FailsafeAct "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/actions/failsafe.ts"
    click PortfolioCheck "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/actions/portfolioCheck.ts"
    click RecoverState "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/actions/recoverState.ts"

    click Bids "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/blur/bids.ts"
    click CollectionsAPI "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/blur/collections.ts"
    click Health "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/blur/healthCheck.ts"

    click CollectionBid "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/os/collectionBid.ts"
    click Login "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/os/login.ts"
    click UserHelper "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/os/user.ts"

    click CollSlice "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/store/collectionsSlice.ts"
    click WalletSlice "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/store/walletsSlice.ts"
    click StoreIndex "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/store/index.ts"

    click StorageColl "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/storage/collections.ts"
    click ConfigStorage "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/storage/collectionsConfig.ts"
    click MyBidsStorage "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/storage/myBids.ts"
    click SuitableStorage "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/storage/suitableCollections.ts"
    click WalletStorage "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/storage/wallets.ts"

    click Axios "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/axios.ts"
    click Discord "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/discord.ts"
    click Flags "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/flags.ts"
    click Log "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/log.ts"
    click Provider "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/provider.ts"
    click Quantity "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/quantity.ts"
    click RateLimit "https://github.com/nfttoolz/blurbiddingbot/blob/main/src/utils/rateLimit.ts"

    %% Styles
    classDef core fill:#e3fcec,stroke:#28a745
    classDef service fill:#e3f3ff,stroke:#007bff
    classDef data fill:#fff4e5,stroke:#fd7e14
    classDef utils fill:#f0f0f0,stroke:#6c757d
    classDef external fill:#ffffff,stroke:#cccccc,stroke-dasharray: 5 5
```
