# moonsong-labs/storage-hub architecture

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

- Interactive diagram: https://gitdiagram.com/moonsong-labs/storage-hub
- Repository: https://github.com/moonsong-labs/storage-hub

## Overview

Based on our analysis of the file tree and README, StorageHub is a storage-optimized parachain designed to operate in the Polkadot and Kusama ecosystems. The project is a complex full-stack Substrate-based blockchain system that includes client-side modules, node implementation, a runtime composed of multiple pallets, underlying primitives, type definitions (via types-bundle), and a robust testing suite including Zombienet integration. The primary goal is to ensure efficient and decentralized storage with both primary (MSP) and backup (BSP) storage providers, supporting interoperability via XCM.

##### Main Components
- Runtime: This is the core Cumulus-based parachain runtime found in the “runtime” directory. It includes the configuration, genesis, and weights along with interface APIs.
- Pallets: Modular runtime components (under the “pallets” directory) that implement various on-chain functionalities such as file storage, payment streams, proofs-dealer, provider randomness, and more. Each pallet might represent a distinct business capability (e.g., file-system operations, bucket NFTs).
- Primitives: Fundamental definitions, constants, types, and traits shared across the runtime and pallets. They add consistency to the overall chain logic and are located in the “primitives” directory.
- Node: The “node” directory contains the implementation of the StorageHub node, including service configuration, RPC services, CLI and task scheduling. This component ties together the runtime execution and off-chain services.
- Client Modules: Components in “client” (including ledger services such as actors-framework, blockchain-service, file-manager, file-transfer-service, forest-manager, indexer-db, indexer-service, and rpc) represent various client-side interactions and service orchestration.
- Types Bundle: The “types-bundle” package contains the shared type definitions (rpc, runtime, types) necessary for frontend clients and API interactions, ensuring consistency with the on-chain types.
- Testing and Dev Tools: The “test” directory provides integration tests (with Zombienet, TypeScript tests, etc.), and additional support files, scripts, and configuration files (e.g., Docker, GitHub workflows) provide deployment and CI/CD capabilities.

##### Relationships and Interactions
- The client-side modules interact with the node via RPC and CLI interfaces.
- The node orchestrates the execution of the runtime, facilitating communication with clients, and managing off-chain tasks (e.g., handling MSP and BSP specific tasks like fee charging, file upload/download, moving buckets, and submitting proofs).
- RPC endpoints, defined in the runtime and updated via the “types-bundle” package, provide external interfaces for clients and third-party applications.
- The pallets (each representing discrete on-chain functionality) are integrated into the runtime and may rely on primitives for shared types and logic.
- Testing components simulate network behavior and validate functionality; they also interact with the node and runtime.

##### Architectural Patterns and Technologies
- Micro-modular design: Each major service (client, node, pallets) is kept isolated in its own directory and works together through well-defined interfaces.
- Substrate/Cumulus Framework: The storage-hub uses a Substrate-based runtime structure with a Cumulus parachain layer, emphasizing module reusability and interoperability.
- XCM Integration: The design supports cross-chain message passing, as evidenced by XCM configuration files in the xcm-simulator directory.
- Strong Type Safety and API Consistency: Via centralized definitions in “types-bundle” and the primitives.
- DevOps and CI/CD: With GitHub Actions workflows and Docker configurations for deployment and testing.

##### Elements
- Optionally, sketch out sub-components such as the XCM interface, detailing how messages route between parachains.
- Configuration and CI/CD integration as a side note to emphasize deployment and operational readiness.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Entities
    ExternalUsers("External Users"):::external
    OtherParachains("Other Parachains"):::external

    %% Frontend/API Layer
    subgraph "Frontend/API Layer"
        clientAF("Actors Framework"):::frontend
        clientBS("Blockchain Service"):::frontend
        clientFM("File Manager"):::frontend
        clientFTS("File Transfer Service"):::frontend
        clientForM("Forest Manager"):::frontend
        clientIndexerDB("Indexer DB"):::frontend
        clientIndexerS("Indexer Service"):::frontend
        clientRPC("RPC"):::frontend
        TypesBundle("Types Bundle"):::frontend
    end

    %% Node Layer
    subgraph "Node Layer"
        NodeService("Node Services"):::nodall
        MSP("MSP (Main Storage Provider)"):::nodall
        BSP("BSP (Backup Storage Provider)"):::nodall
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        RuntimeCore("StorageHub Runtime"):::runtime
        subgraph "Pallets"
            nodeFS("File-System"):::pallet
            nodePS("Payment Streams"):::pallet
            nodePD("Proofs Dealer"):::pallet
            nodePR("Provider Randomness"):::pallet
            nodeP("Providers"):::pallet
            nodeR("Randomness"):::pallet
            nodeBN("Bucket NFTs"):::pallet
        end
        XCMIntegration("XCM Integration"):::runtime
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Primitives("Primitives"):::infrastructure
        Tests("Testing & Dev Tools"):::infrastructure
    end

    %% Connections
    ExternalUsers -->|"initiates"| clientAF
    clientRPC -->|"RPC/CLI"| NodeService
    TypesBundle -->|"Type Sync"| NodeService
    TypesBundle -->|"Type Sync"| RuntimeCore
    NodeService -->|"Executes"| RuntimeCore
    NodeService -->|"Storage Ops"| MSP
    NodeService -->|"Storage Ops"| BSP
    RuntimeCore -->|"Implements"| nodeFS
    RuntimeCore -->|"Implements"| nodePS
    RuntimeCore -->|"Implements"| nodePD
    RuntimeCore -->|"Implements"| nodePR
    RuntimeCore -->|"Implements"| nodeP
    RuntimeCore -->|"Implements"| nodeR
    RuntimeCore -->|"Implements"| nodeBN
    RuntimeCore -->|"XCM Config"| XCMIntegration
    XCMIntegration -->|"XCM Messages"| OtherParachains
    nodeFS -->|"Uses"| Primitives
    nodePS -->|"Uses"| Primitives
    nodePD -->|"Uses"| Primitives
    nodePR -->|"Uses"| Primitives
    nodeP -->|"Uses"| Primitives
    nodeR -->|"Uses"| Primitives
    nodeBN -->|"Uses"| Primitives
    Tests -->|"Validates"| NodeService
    Tests -->|"Validates"| RuntimeCore

    %% Click Events for Client Modules
    click clientAF "https://github.com/moonsong-labs/storage-hub/tree/main/client/actors-framework"
    click clientBS "https://github.com/moonsong-labs/storage-hub/tree/main/client/blockchain-service"
    click clientFM "https://github.com/moonsong-labs/storage-hub/tree/main/client/file-manager"
    click clientFTS "https://github.com/moonsong-labs/storage-hub/tree/main/client/file-transfer-service"
    click clientForM "https://github.com/moonsong-labs/storage-hub/tree/main/client/forest-manager"
    click clientIndexerDB "https://github.com/moonsong-labs/storage-hub/tree/main/client/indexer-db"
    click clientIndexerS "https://github.com/moonsong-labs/storage-hub/tree/main/client/indexer-service"
    click clientRPC "https://github.com/moonsong-labs/storage-hub/tree/main/client/rpc"
    click TypesBundle "https://github.com/moonsong-labs/storage-hub/tree/main/types-bundle/"

    %% Click Events for Node
    click NodeService "https://github.com/moonsong-labs/storage-hub/tree/main/node/"

    %% Click Events for Runtime and Pallets
    click RuntimeCore "https://github.com/moonsong-labs/storage-hub/tree/main/runtime/"
    click nodeFS "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/file-system"
    click nodePS "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/payment-streams"
    click nodePD "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/proofs-dealer"
    click nodePR "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/provider-randomness"
    click nodeP "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/providers"
    click nodeR "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/randomness"
    click nodeBN "https://github.com/moonsong-labs/storage-hub/tree/main/pallets/bucket-nfts"

    %% Click Events for Infrastructure
    click Primitives "https://github.com/moonsong-labs/storage-hub/tree/main/primitives/"
    click Tests "https://github.com/moonsong-labs/storage-hub/tree/main/test/"

    %% Style Classes
    classDef frontend fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef nodall fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef runtime fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef pallet fill:#ead1dc,stroke:#741b47,stroke-width:2px;
    classDef infrastructure fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef external fill:#d0e0e3,stroke:#6d9b98,stroke-width:2px;
```
