# gear-tech/gear architecture

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

- Interactive diagram: https://gitdiagram.com/gear-tech/gear
- Repository: https://github.com/gear-tech/gear

## Overview

##### Main Components
- Developer & Frontend Tools – This includes client-side libraries (gear-js API), the gcli and gclient command line interfaces, and any web dApp examples. These are used by developers to build and interact with applications.
- Node/Network Layer – This layer comprises the blockchain node software (in the “node” directory), chain specification files, and services that run the Gear/Vara network. It is responsible for network consensus, state management, and API endpoints (RPC).
- Runtime Environment – At the heart is the Wasm virtual machine that runs the custom dApp programs (compiled from Rust sources found in many crates). This includes the “core” runtime modules, the “core-backend”, and the runtime’s WASM interfaces such as those in “ethexe”, “runtime”, and “sandbox”.
- Modular Pallets & Core Libraries – The project uses many Rust crates for distinct functionalities. For instance:
– “pallets” directory that contains modules for gas metering, messaging, bank, scheduler, staking, and others.
– Libraries such as “gstd”, “gcore”, “gsdk”, “gprimitives”, “gbuiltins”, etc. Each provides low-level functions, core types, actor-based message handling, and system interfaces.
- Interoperability & External Bridges – Components like “ethexe” (for Ethereum bridging), “gbuiltins”, and related contracts offer compatibility and interaction with external chains or off-chain services.
- DevOps, CI/CD, and Deployment Artifacts – Directories such as “docker”, “ansible”, “.github”, “scripts”, and others hold Dockerfiles, deployment configurations, CI pipelines, and automation scripts that support building, testing, and deploying the platform.

##### Relationships & Data Flow
- User or dApp interactions flow via the JS API (gear-js) to the nodes that run the protocol.
- The node passes messages into the runtime layer (Wasm VM) where custom programs (written in Rust and compiled to Wasm) are executed using the actor model for asynchronous, secure communications.
- The modular pallets (e.g., gear, gear-bank, gear-messenger) interact with each other within the runtime to manage state, balance, consensus, and chain-specific operations.
- External connectivity modules (such as ethexe in the file tree) bridge communications with other networks such as Ethereum.
- DevOps pipelines (CI workflows, Docker images, configuration via Ansible) are shown as supporting layers that manage deployment, testing, and updates.

##### Architectural Patterns & Design Principles
- The Actor Model – Emphasize that all on-chain programs are built on an actor-based messaging system, where messages are the primary unit of communication.
- Modularity & Separation of Concerns – The system is split into many crates and pallets, each handling specific functionalities (e.g., runtime vs. transport vs. consensus).
- High Parallelism – A parallelizable architecture where independent processes (smart contract executions, off-chain computations) work concurrently.
- Extensibility – Modular design using Rust’s crate system allows developers to extend or replace parts of the system (such as through “gsdk” or “gcli”).

##### Technologies/Frameworks to Highlight
- Rust (as the primary language) and Cargo for build management.
- WebAssembly (Wasm) – for near-native execution of smart contracts.
- Substrate – as the foundational blockchain technology powering the nodes and pallets.
- Docker and Ansible – for deployment automation.
- CI/CD tools (GitHub Actions, scripts in “.github” & “scripts” directories) for continuous integration and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Frontend Tools
    subgraph "Developer & Frontend Tools"
        A["gcli"]:::frontend
        B["gclient"]:::frontend
        C["dApp examples"]:::frontend
    end

    %% Node/Network Layer
    subgraph "Node/Network Layer"
        D["Node Software"]:::node
        E["Chain Specification"]:::node
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        F["Core Backend"]:::runtime
        G["Core Modules"]:::runtime
        H["Runtime Interfaces"]:::runtime
        I["Sandbox Environment"]:::runtime
    end

    %% Modular Pallets & Core Libraries
    subgraph "Modular Pallets & Core Libraries"
        J["Pallets"]:::pallet
        K["Common Library"]:::library
        L["Core Processor"]:::library
        M["Core Errors"]:::library
    end

    %% Interoperability & External Bridges
    subgraph "Interoperability & External Bridges"
        N["Ethexe (Ethereum Bridge)"]:::bridge
        O["GBuiltins"]:::bridge
    end

    %% DevOps, CI/CD & Deployment Artifacts
    subgraph "DevOps, CI/CD & Deployment"
        P["Docker & Deployment Scripts"]:::devops
        Q["CI/CD Pipelines"]:::devops
        R["Additional Scripts"]:::devops
    end

    %% Relationships & Data Flow
    %% Developer tools interact with Node layer
    A -->|"uses_API"| D
    B -->|"uses_API"| D
    C -->|"initiates_tx"| D

    %% Internal Node/Network flow
    D -->|"loads"| E
    D -->|"forwards_tx"| F

    %% Runtime Environment interactions
    F -->|"executes_via_actor"| G
    F -->|"dispatches_to"| H
    F -->|"isolated_run"| I

    %% Modular Pallets integration with Runtime
    G -->|"invokes_logic"| J
    H -->|"calls_library"| K
    H -->|"calls_processor"| L
    H -->|"handles_errors"| M

    %% External Bridges integration
    I -->|"bridges_to"| N
    I -->|"utilizes"| O

    %% DevOps support connections
    D -->|"deployment_updates"| P
    F -->|"CI_integration"| Q
    J -->|"automation_scripts"| R

    %% Click Events for Developer & Frontend Tools
    click A "https://github.com/gear-tech/gear/tree/master/gcli/"
    click B "https://github.com/gear-tech/gear/tree/master/gclient/"
    click C "https://github.com/gear-tech/gear/tree/master/examples/"

    %% Click Events for Node/Network Layer
    click D "https://github.com/gear-tech/gear/tree/master/node/"
    click E "https://github.com/gear-tech/gear/tree/master/node/service/src/chain_spec/"

    %% Click Events for Runtime Environment
    click F "https://github.com/gear-tech/gear/tree/master/core-backend/"
    click G "https://github.com/gear-tech/gear/tree/master/core/"
    click H "https://github.com/gear-tech/gear/tree/master/runtime/"
    click I "https://github.com/gear-tech/gear/tree/master/sandbox/"

    %% Click Events for Modular Pallets & Core Libraries
    click J "https://github.com/gear-tech/gear/tree/master/pallets/"
    click K "https://github.com/gear-tech/gear/tree/master/common/"
    click L "https://github.com/gear-tech/gear/tree/master/core-processor/"
    click M "https://github.com/gear-tech/gear/tree/master/core-errors/"

    %% Click Events for Interoperability & External Bridges
    click N "https://github.com/gear-tech/gear/tree/master/ethexe/"
    click O "https://github.com/gear-tech/gear/tree/master/gbuiltins/"

    %% Click Events for DevOps, CI/CD & Deployment
    click P "https://github.com/gear-tech/gear/tree/master/docker/"
    click Q "https://github.com/gear-tech/gear/tree/master/.github/"
    click R "https://github.com/gear-tech/gear/tree/master/scripts/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef node fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef runtime fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef pallet fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef library fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef bridge fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef devops fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
```
