# kunkunsh/kkrpc architecture

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

- Interactive diagram: https://gitdiagram.com/kunkunsh/kkrpc
- Repository: https://github.com/kunkunsh/kkrpc

## Overview

##### Project Type & Purpose
- This is an RPC library meant to simplify bi-directional communications between processes. Its design abstracts “remote” function calls as local ones using a central RPCChannel and pluggable IO adapters.
- It is used as a standalone package but also powers examples in multiple environments (Node, Deno, Bun, web workers, iframes, Chrome extensions and Tauri apps).

##### Analyzing the File Structure
- At the top level, you have configuration files (e.g., .npmrc, .prettierrc, .gitignore) plus directories for docs, examples, and packages.
- The “packages/kkrpc” directory holds the core implementation including adapters (in src/adapters), utilities, and type definitions. This shows the main business logic centered on the RPCChannel and IoInterface.
- There are also testing folders (e.g., __tests__) and related build and configuration files that support CI/CD and automated documentation generation.

##### Core Architectural Components
a. Core Library:
- RPCChannel: The central component handling the bidirectional RPC communication.
- IoInterface: The abstract IO definition that is implemented by various adapters.
- Serialization Mechanism: Supporting both “json” and “superjson” formats.

b. Adapters/Implementations (Using IoInterface):
- Standard I/O adapters: e.g., NodeIo, handling stdio streams.
- Web adapters: for workers, iframes, browser modules (ChromeContentIO, ChromeBackgroundIO, WorkerChildIO, WorkerParentIO, IframeChildIO, IframeParentIO).
- HTTP Adapters: HTTPClientIO and HTTPServerIO for REST-like RPC over HTTP.
- Tauri and other runtime-specific adapters: Found under examples/tauri-demo and specific adapter implementations in packages/kkrpc/src/adapters.

c. API Abstractions:
- LocalAPI: The set of functions exposed for remote calls.
- RemoteAPI: The API callable on the local side which represents the other endpoint’s functionality.
- The getAPI() method that converts the remote side’s capabilities into local-callable functions.

d. Supporting Components:
- Testing and examples: Each example demonstrates the integration of specific adapters with the core RPCChannel.
- Build and config files to support TypeScript compilation, dependency management, and CI pipelines.

a. Start by drawing a central block labeled “Core kkrpc Library” that encapsulates:
- RPCChannel
- IoInterface
- Serialization options (json / superjson)
- API Abstractions (LocalAPI and RemoteAPI)

b. Around the central block, create separate nodes for each adapter/environment:
- Stdio Environment:
- NodeIo and similar classes for Node, Deno, Bun.
- Web Environment:
- Worker Adapters (WorkerChildIO, WorkerParentIO)
- Iframe Adapters (IframeChildIO, IframeParentIO)
- HTTP Environment:
- Browser/Chrome Extension:
- ChromeBackgroundIO and ChromeContentIO nodes, indicating communication between a background script and content script.
- Tauri Environment:
- Tauri-specific adapter (e.g., TauriShellStdio) and integration with plugins.

c. How the “Core Library” connects to each adapter demonstrating how RPC messages and IO implementations are passed.
- Bidirectional communication between the server and client components in each environment.

d. For each adapter node, include a brief label or sub-note indicating the underlying technology or runtime specifics (for example, “Node: process.stdin/stdout”, “HTTP: REST-like message transmission”, “Worker: postMessage”).

e. To capture the testing/demonstration aspects:
- That these examples serve as integration tests and usage scenarios that further validate the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core kkrpc Library"
        RPCChannel["RPCChannel"]:::core
        IoInterface["IoInterface"]:::core
        Serialization["Serialization (json/superjson)"]:::core
        API["API Abstractions (LocalAPI & RemoteAPI)"]:::core
    end

    %% Adapter Implementations
    subgraph "Adapter Implementations"
        subgraph "Standard I/O Adapters"
            NodeAdapter["Node Io Adapter\n(process.stdio)"]:::adapter
            BunAdapter["Bun Io Adapter"]:::adapter
            DenoAdapter["Deno Io Adapter"]:::adapter
        end

        subgraph "Web Adapters"
            WorkerAdapter["Worker Adapter\n(postMessage)"]:::adapter
            IframeAdapter["Iframe Adapter\n(iframe messaging)"]:::adapter
        end

        subgraph "HTTP Adapters"
            HTTPAdapter["HTTP Adapter\n(REST-like)"]:::adapter
        end

        subgraph "Browser/Extension Adapters"
            ChromeCore["Chrome Adapter (Core)"]:::adapter
            ChromeAdapter["Chrome Adapter (Impl)"]:::adapter
        end

        subgraph "Tauri Environment"
            TauriAdapter["Tauri Adapter"]:::adapter
        end
    end

    %% Example Implementations
    subgraph "Example Implementations"
        TauriExample["Tauri Example"]:::example
        HTTPExample["HTTP Example"]:::example
        WorkerExample["Worker/Web Example"]:::example
    end

    %% Connections from Core Library to Adapters
    RPCChannel -->|"connects"| NodeAdapter
    RPCChannel -->|"connects"| BunAdapter
    RPCChannel -->|"connects"| DenoAdapter
    RPCChannel -->|"connects"| WorkerAdapter
    RPCChannel -->|"connects"| IframeAdapter
    RPCChannel -->|"connects"| HTTPAdapter
    RPCChannel -->|"connects"| ChromeCore
    RPCChannel -->|"connects"| ChromeAdapter
    RPCChannel -->|"connects"| TauriAdapter

    %% IoInterface implementation relationships
    IoInterface -->|"implementedBy"| NodeAdapter
    IoInterface -->|"implementedBy"| BunAdapter
    IoInterface -->|"implementedBy"| DenoAdapter
    IoInterface -->|"implementedBy"| WorkerAdapter
    IoInterface -->|"implementedBy"| IframeAdapter
    IoInterface -->|"implementedBy"| HTTPAdapter
    IoInterface -->|"implementedBy"| ChromeAdapter
    IoInterface -->|"implementedBy"| TauriAdapter

    %% Example usage connections
    TauriExample -->|"uses"| TauriAdapter
    HTTPExample -->|"uses"| HTTPAdapter
    WorkerExample -->|"uses"| WorkerAdapter
    WorkerExample -->|"uses"| IframeAdapter

    %% Click Events for Core Library Components
    click RPCChannel "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/channel.ts"
    click IoInterface "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/interface.ts"
    click Serialization "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/serialization.ts"

    %% Click Events for Adapter Implementations
    click NodeAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/node.ts"
    click BunAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/bun.ts"
    click DenoAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/deno.ts"
    click WorkerAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/worker.ts"
    click IframeAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/iframe.ts"
    click HTTPAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/http.ts"
    click ChromeCore "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/chrome.ts"
    click ChromeAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/chrome.ts"
    click TauriAdapter "https://github.com/kunkunsh/kkrpc/blob/main/packages/kkrpc/src/adapters/tauri.ts"

    %% Click Events for Example Implementations
    click TauriExample "https://github.com/kunkunsh/kkrpc/tree/main/examples/tauri-demo"
    click HTTPExample "https://github.com/kunkunsh/kkrpc/tree/main/examples/http-demo"
    click WorkerExample "https://github.com/kunkunsh/kkrpc/tree/main/examples/deno-webworker-demo"
    click WorkerExample "https://github.com/kunkunsh/kkrpc/tree/main/examples/iframe-worker-demo"

    %% Styling
    classDef core fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef adapter fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef example fill:#90EE90,stroke:#228B22,stroke-width:2px;
```
