# iamfat/json-rpc architecture

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

- Interactive diagram: https://gitdiagram.com/iamfat/json-rpc
- Repository: https://github.com/iamfat/json-rpc

## Overview

##### Project type and purpose
- This is an open-source TypeScript library for implementing JSON-RPC clients/servers, with optional “SmartRPC” sugar on top. It targets multiple environments (Node, browser, React Native) and is packaged via esbuild.

##### File structure
- Top-level config:
- .gitignore, .npmignore, .prettierrc.cjs, tsconfig.json (code style & TS config)
- package.json, pnpm-lock.yaml (package metadata & lockfile)
- esbuild.mjs (build script)
- Source code under src/:
- RPC.ts – core JSON-RPC implementation (call, notify, receive, events)
- SmartRPC.ts – wrapper that “smartifies” RPC with namespaced method calls
- index.ts – main entry point that re-exports Rpc and SmartRPC
- index.browser.ts, index.rn.ts – environment-specific entry shims
- spec/ contains Jasmine tests validating rpc behavior.

##### README for additional insights
- Usage examples show:
- Instantiating JsonRPC with a send callback & optional logger
- rpc.call(), rpc.notify(), rpc.receive()
- rpc.stat() for introspection
- SmartRPC offering rpc.Namespace1.Namespace2.Method() elegance

a. Main components:
- Core RPC Engine (RPC.ts)
- SmartRPC Wrapper (SmartRPC.ts)
- Transport Layer (user-supplied send function + receive pipeline)
- Event/Logging subsystem (logger interface, events)
- Environment Adapters (index.browser.ts, index.rn.ts)
- Build Tool (esbuild.mjs)
- Test Suite (spec/)
b. Relationships & interactions:
- Consumer code invokes `new JsonRPC(sendFn, options)` → Core RPC Engine
- Core Engine → uses Transport Layer to emit JSON payloads
- Incoming payloads → passed to `rpc.receive()` → Core Engine parses & emits events or resolves promises
- SmartRPC wraps Core Engine, intercepts calls to generate namespaces → forwards to Core Engine
- Environment Adapters bind the library to specific globals/APIs in browser or React Native
c. Architectural patterns/design principles:
- Dependency Injection for Transport (send callback) & Logger
- Wrapper/Decorator pattern in SmartRPC to extend Core RPC
- Modular single-responsibility files (one class or role per file)
- Test-driven design (spec/ verifies core RPC behavior)
d. Key technologies/frameworks:
- TypeScript → strong typing
- esbuild → fast bundling for multiple targets
- Jasmine → test runner in spec/
- npm/pnpm → package management

##### Detailed breakdown
- Block: Consumer Application (left side)
– calls rpc.call()/rpc.notify() →
– SmartRPC namespace calls → Core RPC Engine
- Block: SmartRPC.ts (on top of Core RPC)
- Block: RPC.ts (center)
- Methods: call(), notify(), receive(), on(event), stat()
- Block: Transport Layer (right side)
- sendFn (injected) ← RPC.ts → JSON over network
- network ←→ JSON data → receive()
- Block: Logger (attached to RPC.ts, optional)
- Block: Environment Shims (bottom)
- index.browser.ts
- index.rn.ts
- index.ts (exports correct shim based on build)
- Block: Build Pipeline (esbuild.mjs) connecting src/ → dist/
- Block: Test Suite (spec/) verifying RPC behavior

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Consumer
        ConsumerApp["Consumer Application"]:::external
    end

    subgraph Library
        SmartRPC["SmartRPC Wrapper"]:::wrapper
        RPC["Core RPC Engine"]:::core
        Logger["Logger Interface"]:::core
        Transport["Transport Layer\n(sendFn injected)"]:::external
    end

    ConsumerApp -->|"rpc.call()/rpc.notify()"| SmartRPC
    SmartRPC -->|"forwards calls"| RPC
    RPC -->|"uses sendFn"| Transport
    Transport -->|"incoming JSON"| RPC
    RPC -->|"emits events/promises"| ConsumerApp
    RPC -->|"optional logger"| Logger

    subgraph "Environment Adapters"
        MainEntry["Main Entry Point"]:::adapter
        BrowserShim["Browser Shim"]:::adapter
        RNSlim["React Native Shim"]:::adapter
    end

    MainEntry --> BrowserShim
    MainEntry --> RNSlim
    MainEntry --> RPC

    subgraph "Build Pipeline"
        Esbuild["esbuild.mjs"]:::infra
    end

    Esbuild --> MainEntry

    subgraph "Test Suite"
        Specs["spec/"]:::infra
    end

    Specs --> RPC
    Specs --> SmartRPC

    click RPC "https://github.com/iamfat/json-rpc/blob/master/src/RPC.ts"
    click SmartRPC "https://github.com/iamfat/json-rpc/blob/master/src/SmartRPC.ts"
    click BrowserShim "https://github.com/iamfat/json-rpc/blob/master/src/index.browser.ts"
    click RNSlim "https://github.com/iamfat/json-rpc/blob/master/src/index.rn.ts"
    click MainEntry "https://github.com/iamfat/json-rpc/blob/master/src/index.ts"
    click Esbuild "https://github.com/iamfat/json-rpc/blob/master/esbuild.mjs"
    click Specs "https://github.com/iamfat/json-rpc/tree/master/spec/"

    classDef core fill:#cff,stroke:#00f,stroke-width:2px
    classDef wrapper fill:#cfc,stroke:#0a0,stroke-width:2px
    classDef adapter fill:#cfc,stroke:#0a0,stroke-width:2px
    classDef external fill:#eee,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
    classDef infra fill:#fcf,stroke:#c0f,stroke-width:2px
```
