# stabilityprotocol/stability architecture

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

- Interactive diagram: https://gitdiagram.com/stabilityprotocol/stability
- Repository: https://github.com/stabilityprotocol/stability

## Overview

##### Main Components
- Node & Runtime Core:
- The "node" directory contains the main node application with chain specifications, RPC implementations, and client services.
- The "runtime" folder holds the blockchain runtime code and configuration, including pallets integration.
- Pallets and Precompiles:
- The "pallets" directory comprises many custom pallets (e.g., custom-balances, fee management, sponsored transactions, validator-set) that are the functional building blocks of the blockchain.
- The "precompiles" directory hosts modules for precompiled contracts, which are used to enhance or accelerate certain functionalities.
- Client and Metrics:
- The "client" folder (with submodules like authorship and proposer-metrics) handles node-specific tasks such as block authorship and performance metrics.
- Supporting Tools and Utilities:
- The "stability-cli" and "stability-rpc" directories provide command-line tools and RPC interfaces for managing the blockchain.
- The "utils" folder and "primitives" directories offer shared logic, APIs, and helper libraries for account representation, transaction validation, and Ethereum-specific operations.
- Docker and Deployment:
- The "docker" directory, along with accompanying CI/CD configurations (under .github/workflows), provides deployment and testing scripts, supporting containerized environments.

##### Relationships and Interactions
- How the Node (client + core node components) interacts with the Runtime:
- The Node communicates with the runtime through RPC interfaces (found in node/src/rpc) and initiates protocols like consensus.
- Runtime-Pallet Integration:
- The runtime is composed of various pallets (custom balances, fee selectors, validator management, etc.), each responsible for a blockchain module. Indicate how these pallets interact internally and expose APIs to the runtime.
- External and Third-Party Services:
- Ethereum compatibility layer provided by Frontier—a bridge that handles Ethereum-like API requests.
- Also, show integration with monitoring tools (from the “docker/monitoring” folder, which includes Prometheus and Grafana configurations) for system observability.
- Client and CLI Components:
- How the stability-cli and RPC components interact with the node, enabling administrative controls, manual block sealing, and overall chain management.

##### Architectural Patterns & Technologies
- Modular Architecture:
- Modular design of the blockchain, where each pallet is a distinct component that plugs into the runtime.
- Consensus & Governance:
- Dockerized Deployment:
- That Docker and container orchestration (via docker-compose) are used for deployment, testing, and monitoring.
- CI/CD Integration:
- How workflows are defined in GitHub Actions for building, testing, and deploying the blockchain code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Node & Runtime Core"
        Node["Node (chain_spec, RPC, client services)"]:::core
        Runtime["Runtime (pallet integration)"]:::core
    end

    subgraph "Pallets and Precompiles"
        Pallets["Custom Pallets"]:::pallet
        Precompiles["Precompiles"]:::pallet
    end

    subgraph "Client and Metrics"
        Client["Client (authorship, proposer-metrics)"]:::client
        CLI["CLI (stability-cli)"]:::client
        RPC_Interface["RPC Interface (stability-rpc)"]:::client
    end

    subgraph "Supporting Tools and Utilities"
        Primitives["Primitives"]:::util
        Utils["Utils"]:::util
    end

    subgraph "Docker & Deployment"
        Docker["Docker (deployment, monitoring)"]:::deploy
        CI_CD["CI/CD (.github/workflows)"]:::deploy
    end

    Frontier["Frontier (Ethereum Compatibility)"]:::external

    %% Relationships between components
    CLI -->|"triggers"| Node
    RPC_Interface -->|"sends_RPC"| Node
    Client -->|"communicates"| Node
    Node -->|"executes"| Runtime
    Runtime -->|"integrates"| Pallets
    Runtime -->|"integrates"| Precompiles
    Runtime -->|"exposes"| Frontier
    CI_CD -->|"deploys"| Docker
    Docker -->|"deploys/monitors"| Node

    %% Click Events for component mapping
    click Node "https://github.com/stabilityprotocol/stability/tree/main/node/"
    click Runtime "https://github.com/stabilityprotocol/stability/tree/main/runtime/"
    click Pallets "https://github.com/stabilityprotocol/stability/tree/main/pallets/"
    click Precompiles "https://github.com/stabilityprotocol/stability/tree/main/precompiles/"
    click Client "https://github.com/stabilityprotocol/stability/tree/main/client/"
    click CLI "https://github.com/stabilityprotocol/stability/tree/main/stability-cli/"
    click RPC_Interface "https://github.com/stabilityprotocol/stability/tree/main/stability-rpc/"
    click Primitives "https://github.com/stabilityprotocol/stability/tree/main/primitives/"
    click Utils "https://github.com/stabilityprotocol/stability/tree/main/utils/"
    click Docker "https://github.com/stabilityprotocol/stability/tree/main/docker/"
    click CI_CD "https://github.com/stabilityprotocol/stability/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef pallet fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef client fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef util fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef deploy fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
```
