# paritytech/jsonrpc architecture

> Architecture diagram of the GitHub repository paritytech/jsonrpc, 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/paritytech/jsonrpc
- Repository: https://github.com/paritytech/jsonrpc

## Overview

This project is a Rust-based implementation of the JSON-RPC 2.0 specification, designed to be transport agnostic. It’s organized as a multi-crate repository where each sub-project (or “crate”) targets a specific aspect—whether it be the core JSON-RPC logic, client support, deriving RPC traits via macros, or actual transport implementations (HTTP, IPC, TCP, WS, stdio). The primary goal is to offer a modular JSON-RPC solution where different transport servers plug into a common core, along with support for advanced features like publish/subscribe.

##### Main Components
- Core Library (“core”): Contains the essential logic for handling JSON-RPC calls, middleware, error handling, and the basic types for requests, responses, and delegating methods.
- Core Client (“core-client”): Focused on the client-side implementation that enables invoking JSON-RPC methods.
- Transport Servers: Multiple crates implement transport-specific servers:
– HTTP (jsonrpc-http-server)
– IPC (jsonrpc-ipc-server)
– TCP (jsonrpc-tcp-server)
– WebSocket (jsonrpc-ws-server)
– Stdio (jsonrpc-stdio-server)
- Derive Macros (“derive”): Provides procedural macros to easily implement RPC traits and generate delegates.
- Server Utilities (“server-utils”): Contains helper functions and modules for CORS, sessions, stream management, and other server-side utilities.
- PubSub Support (“pubsub”): Implements publish/subscribe functionality for handling subscriptions beyond basic RPC call/response.

##### Relationships and Interactions
- The Core acts as the central engine. All transport servers and the client wrap around this core logic.
- When a request comes in via a transport server (for example, HTTP), the server receives the request and routes it to the core’s IoHandler. The IoHandler processes the request using methods (which might have been generated/enhanced by derive macros) and returns a response.
- The Client component in “core-client” sends JSON-RPC requests to any of these transport layers, receiving the processed results from the server.
- The Derive crate is used to automatically generate trait delegates and helpers for converting high-level RPC interface definitions into code that interacts with the core layer.
- Server Utilities provide additional functionality (like logging, session management, and middleware support) that is shared across different transport implementations.
- PubSub extends the core functionality to support subscription-based interactions which is integrated into one or more transport servers.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each crate has a distinct responsibility (core processing, transport handling, client-side interactions, etc.) ensuring modularity.
- Transport Agnosticism: The core JSON-RPC logic remains independent of the transport layer. This decoupling allows simple swapping or additions of new transport protocols.
- Extensibility via Macros: The “derive” crate aids in reducing boilerplate for implementing RPC methods, promoting DRY code and ease of use.
- Utility Layer: The server utilities abstract common patterns such as session management and error logging.
- Example Driven: The presence of multiple examples in different directories (e.g., in “core/examples”, “derive/examples”) illustrates a focus on clarity and ease-of-adoption.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Components"
        core["JSON-RPC Core Library"]
        client["Core Client"]
        derive["Derive Macros"]
    end

    subgraph "Transport Servers"
        http["HTTP Transport Server"]
        ipc["IPC Transport Server"]
        tcp["TCP Transport Server"]
        ws["WebSocket Transport Server"]
        stdio["Stdio Transport Server"]
    end

    pubsub["PubSub Module"]
    utils["Server Utilities"]
    examples["Examples"]

    %% Core interactions
    client -->|"Send_Request"| core
    core -->|"Return_Response"| client

    %% Transport Servers interactions with Core
    http -->|"Route_Request"| core
    ipc -->|"Route_Request"| core
    tcp -->|"Route_Request"| core
    ws -->|"Route_Request"| core
    stdio -->|"Route_Request"| core

    core -->|"Return_Response"| http
    core -->|"Return_Response"| ipc
    core -->|"Return_Response"| tcp
    core -->|"Return_Response"| ws
    core -->|"Return_Response"| stdio

    %% Client sending JSON-RPC request via a transport
    client -->|"JSON-RPC_Request"| http

    %% Derive macros interactions
    derive -->|"Delegate_Generation"| core
    derive -->|"Delegate_Generation"| client

    %% Server Utilities support to Transport Servers
    utils -->|"Utility_Functions"| http
    utils -->|"Utility_Functions"| ipc
    utils -->|"Utility_Functions"| tcp
    utils -->|"Utility_Functions"| ws
    utils -->|"Utility_Functions"| stdio

    %% PubSub integration
    pubsub -->|"Subscription_Support"| core
    pubsub -->|"Subscription_Support"| http
    pubsub -->|"Subscription_Support"| ipc
    pubsub -->|"Subscription_Support"| tcp
    pubsub -->|"Subscription_Support"| ws
    pubsub -->|"Subscription_Support"| stdio

    %% Examples showing usage
    examples -->|"Usage_Examples"| core
    examples -->|"Usage_Examples"| derive

    %% Click Events
    click core "https://github.com/paritytech/jsonrpc/tree/master/core/"
    click client "https://github.com/paritytech/jsonrpc/tree/master/core-client/"
    click derive "https://github.com/paritytech/jsonrpc/tree/master/derive/"
    click http "https://github.com/paritytech/jsonrpc/tree/master/http/"
    click ipc "https://github.com/paritytech/jsonrpc/tree/master/ipc/"
    click tcp "https://github.com/paritytech/jsonrpc/tree/master/tcp/"
    click ws "https://github.com/paritytech/jsonrpc/tree/master/ws/"
    click stdio "https://github.com/paritytech/jsonrpc/tree/master/stdio/"
    click pubsub "https://github.com/paritytech/jsonrpc/tree/master/pubsub/"
    click utils "https://github.com/paritytech/jsonrpc/tree/master/server-utils/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1A5276,stroke-width:2px;
    classDef client fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef transport fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef macro fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef util fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef pubsub fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef example fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;

    class core core;
    class client client;
    class derive macro;
    class http transport;
    class ipc transport;
    class tcp transport;
    class ws transport;
    class stdio transport;
    class pubsub pubsub;
    class utils util;
    class examples example;
```
