# paritytech/jsonrpsee architecture

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

## Overview

##### Main Components
- Client Subsystems: The project includes different client implementations found under the “client” directory. There are several clients:
– HTTP Client (“client/http-client”)
– WebSocket Client (“client/ws-client”)
– WASM Client (“client/wasm-client”)
- Server Subsystem: The “server” directory contains the server implementation which leverages the core and supports middleware (for both HTTP and RPC) and custom transport handling (HTTP and WebSocket). Create a block labeled “Server” that shows these internal components:
– Middleware (with HTTP and RPC variants)
– Transport layers (HTTP transport, WS transport)
- Proc Macros: The “proc-macros” directory contains code generation tools that automate client/server code generation with annotations. Mark this as an “Extension” or “Code Generation” component that interacts with or generates code for both client and server modules.
- Examples/Tests/Benchmarks: Although not part of the production architecture, the “examples”, “tests”, “benches”, and “test-utils” directories highlight usage patterns and integration tests. Represent them as auxiliary components that validate or demonstrate how the main components interact.

##### Relationships and Data Flow
- The “Server” processes requests (hinting at the inclusion of middleware layers) and ultimately depends on the core error handling and response-building logic.

##### Architectural Patterns & Design Principles
- Modularization: Emphasize the separation between transport layers, core logic, middleware, and code generation – key for extensibility.
- Abstraction: A clear client abstraction is provided through transport modules, allowing custom transport implementations.
- Asynchronous Design: The entire architecture is built around async/await patterns, ensuring non-blocking IO for both the client and server.
- Extensibility via Middleware: The server supports custom middleware, which can intercept, log and modify JSON-RPC calls.
- Code Generation: Utilization of Rust proc macros to reduce boilerplate and enforce a defined RPC schema.

##### Technology and Tools
- Language: Rust is the main technology.
- Async: Leverages async/await in Rust.
- Middleware: Server side middleware layers indicate pluggability.
- WebAssembly: The wasm client is available for web integration.
- Testing/Benchmarking: There are dedicated folders for robust testing and benchmarks.

##### Elements
- Inline Annotations: Optionally include notes or callouts stating key characteristics such as “async/await”, “middleware layering”, or “transport abstraction”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Proc Macros Component
    ProcMacros["Proc Macros (Code Generation)"]:::proc

    %% Clients Subgraph
    subgraph "Clients"
        HTTP_Client["HTTP Client"]:::client
        WS_Client["WebSocket Client"]:::client
        WASM_Client["WASM Client"]:::client
    end

    %% Core and Shared Types
    Core["jsonrpsee Core"]:::core
    Types["Shared Types"]:::types

    %% Server Subgraph with Middleware
    subgraph "Server"
        Server["Server"]:::server
        Middleware_HTTP["Middleware (HTTP)"]:::middleware
        Middleware_RPC["Middleware (RPC)"]:::middleware
        Server --- Middleware_HTTP
        Server --- Middleware_RPC
    end

    %% Auxiliary Subgraph for Examples, Benchmarks, and Tests
    subgraph "Auxiliary"
        EX["Examples"]:::aux
        BN["Benches"]:::aux
        TS["Tests"]:::aux
        TU["Test Utils"]:::aux
    end

    %% Relationships and Data Flow
    %% Proc Macros interact with Clients and Server
    ProcMacros -->|"generates"| HTTP_Client
    ProcMacros -->|"generates"| WS_Client
    ProcMacros -->|"generates"| WASM_Client
    ProcMacros -->|"generates"| Server

    %% Clients depend on Core
    HTTP_Client -->|"depends"| Core
    WS_Client -->|"depends"| Core
    WASM_Client -->|"depends"| Core

    %% Clients make requests to Server
    HTTP_Client -->|"calls"| Server
    WS_Client -->|"calls"| Server
    WASM_Client -->|"calls"| Server

    %% Server uses Core
    Server -->|"uses"| Core

    %% Core uses Shared Types
    Core -->|"utilizes"| Types

    %% Auxiliary components demonstrate usage of Core
    EX -->|"demonstrates"| Core
    BN -->|"demonstrates"| Core
    TS -->|"demonstrates"| Core
    TU -->|"demonstrates"| Core

    %% Styling Classes
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef client fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef server fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef middleware fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef proc fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef types fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef aux fill:#EEE8AA,stroke:#000,stroke-width:2px;

    %% Click Events
    click ProcMacros "https://github.com/paritytech/jsonrpsee/blob/master/proc-macros/src/lib.rs"
    click HTTP_Client "https://github.com/paritytech/jsonrpsee/blob/master/client/http-client/src/client.rs"
    click WS_Client "https://github.com/paritytech/jsonrpsee/blob/master/client/ws-client/src/lib.rs"
    click WASM_Client "https://github.com/paritytech/jsonrpsee/blob/master/client/wasm-client/src/lib.rs"
    click Core "https://github.com/paritytech/jsonrpsee/blob/master/core/Cargo.toml"
    click Server "https://github.com/paritytech/jsonrpsee/blob/master/server/src/server.rs"
    click Middleware_HTTP "https://github.com/paritytech/jsonrpsee/tree/master/server/src/middleware/http"
    click Middleware_RPC "https://github.com/paritytech/jsonrpsee/tree/master/server/src/middleware/rpc"
    click Types "https://github.com/paritytech/jsonrpsee/blob/master/types/src/lib.rs"
    click EX "https://github.com/paritytech/jsonrpsee/tree/master/examples"
    click BN "https://github.com/paritytech/jsonrpsee/tree/master/benches"
    click TS "https://github.com/paritytech/jsonrpsee/tree/master/tests"
    click TU "https://github.com/paritytech/jsonrpsee/tree/master/test-utils"
```
