# iosh/cive architecture

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

- Interactive diagram: https://gitdiagram.com/iosh/cive
- Repository: https://github.com/iosh/cive

## Overview

##### Main Components
- Client Libraries: Represented under the directories “src/clients” and “src/clients/transports”. This component handles creation of public and wallet clients and managing the underlying network transports (HTTP, WebSocket, custom, and fallback).
- Blockchain Actions: Located under “src/actions” with submodules for public actions (e.g., “call”, “getBalance”, “getBlock”, etc.) and wallet actions (e.g., “sendTransaction”, “signMessage”, “writeContract”, etc.). These actions encapsulate the interactions with the blockchain.
- Accounts Module: Found in “src/accounts”, this component provides functionalities such as deriving accounts from mnemonic, private key conversions, cryptographic signing, and message verification.
- Chain Definitions: Located under “src/chains/definitions” (e.g., localhost, mainnet, testnet). These definitions configure the blockchain network details.
- Utilities, Formatters, and Helpers: Spread across “src/utils”, “src/utils/abi”, “src/utils/address”, etc. They offer low-level operations for ABI encoding/decoding, address formatting, error handling, and transaction serialization.
- Types and Error Handling: Under “src/types” and “src/errors”, this part defines the common types (ABI specifications, contract types, transaction types, etc.) and standardized error objects for robust error handling.
- Documentation and Examples: Although separate from the core runtime, the “site” and “examples” directories provide real-world usage examples and documentation that reinforces the intended interactions between components.

##### Relationships and Interactions
- Blockchain Actions serve as the API layer that abstracts the complex interactions. They use:
– The Accounts Module for cryptographic signing and account-related operations.
– The Chain Definitions for network-specific operations.
– The underlying Client libraries when executing transactions or contract interactions.
- Utilities and Formatters support all these components by ensuring proper data conversion, error handling, and logging.
- Types and Errors are cross-cutting concerns that inform the design and data flow throughout the system.

##### Architectural Patterns / Design Principles
- Modular Design: Each major functionality (clients, accounts, actions, chains, etc.) is encapsulated in its own module, enabling separation of concerns.
- Layered Abstraction: At the base, low-level transports and utilities build up to higher-level blockchain interactions and client APIs.
- Extensibility: The structure (directories like “src/clients/transports” and “src/actions”) is designed to easily add new transports or actions in the future.
- Test-Driven Development: With a dedicated “test” directory and extensive tests in each module (notice the *.test.ts files), emphasis is placed on reliability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Transports
    subgraph "Clients & Transports"
        C1["Clients Core"]:::client
        T1["Network Transports"]:::client
        C1 -->|"uses"| T1
    end

    %% Blockchain Actions
    subgraph "Blockchain Actions"
        PA["Public Actions"]:::actions
        WA["Wallet Actions"]:::actions
    end

    %% Accounts and Chain Definitions
    A["Accounts Module"]:::accounts
    CD["Chain Definitions"]:::chain

    %% Utilities & Formatters
    subgraph "Utilities & Formatters"
        GU["General Utilities"]:::utils
        ABI["ABI Utilities & Helpers"]:::utils
        AD["Address Utilities & Helpers"]:::utils
    end

    %% Types & Errors
    subgraph "Types & Errors"
        TD["Type Definitions"]:::types
        ED["Error Definitions"]:::types
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        DG["Documentation & Guides"]:::docs
        UE["Usage Examples"]:::docs
    end

    %% Connections between main components
    PA -->|"calls"| C1
    WA -->|"calls"| C1
    WA -->|"uses"| A
    PA -->|"dependsOn"| CD
    WA -->|"dependsOn"| CD

    %% Utilities dotted support arrows
    GU ---|"supports"| C1
    GU ---|"supports"| PA
    GU ---|"supports"| WA
    ABI ---|"encodes"| PA
    AD ---|"formats"| WA

    %% Types & Errors dotted support arrows
    TD ---|"informs"| PA
    TD ---|"informs"| WA
    ED ---|"handlesErrors"| WA

    %% Click Events
    click C1 "https://github.com/iosh/cive/tree/main/src/clients"
    click T1 "https://github.com/iosh/cive/tree/main/src/clients/transports"
    click PA "https://github.com/iosh/cive/tree/main/src/actions/public"
    click WA "https://github.com/iosh/cive/tree/main/src/actions/wallet"
    click A "https://github.com/iosh/cive/tree/main/src/accounts"
    click CD "https://github.com/iosh/cive/tree/main/src/chains/definitions"
    click GU "https://github.com/iosh/cive/tree/main/src/utils"
    click ABI "https://github.com/iosh/cive/tree/main/src/utils/abi"
    click AD "https://github.com/iosh/cive/tree/main/src/utils/address"
    click TD "https://github.com/iosh/cive/tree/main/src/types"
    click ED "https://github.com/iosh/cive/tree/main/src/errors"
    click DG "https://github.com/iosh/cive/tree/main/site"
    click UE "https://github.com/iosh/cive/tree/main/examples"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef actions fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef accounts fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef chain fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef utils fill:#D8BFD8,stroke:#000,stroke-width:1px;
    classDef types fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
